@paprika/form-element

Description

FormElement component displays a user input field

Installation

yarn add @paprika/form-element

or with npm:

npm install @paprika/form-element

Props

FormElement

| Prop | Type | required | default | Description | | ----------- | -------------------------------------------------------------------------------------------- | -------- | ----------------------------- | -------------------------------------------------------------------------------------- | | children | node | true | - | FormElement sub components and layout elements. | | hasFieldSet | bool | false | false | FormElement contains multiple children so Renders a legend element instead of label. | | id | string | false | "" | id attribute for the input field DOM element (will be auto-generated if not supplied). | | isDisabled | bool | false | false | Should be disabled or not, default is false. | | isOptional | bool | false | false | If input is an optional field and should be indicated. | | isRequired | bool | false | false | If input is a required field. | | size | [ FormElement.types.size.SMALL, FormElement.types.size.MEDIUM, FormElement.types.size.LARGE] | false | FormElement.types.size.MEDIUM | Size of the label, error, help and description (font size, min-height, padding, etc). |

FormElement.Content

| Prop | Type | required | default | Description | | -------- | ----------- | -------- | ------- | --------------------------------------------------------------------------------------------- | | children | [func,node] | true | - | Input field and layout elements. May be a render function with a11yProps object and refLabel. |

a11yProps includes: { id, disabled?, "aria-disabled"?, "aria-describedby"?, "aria-required"? } refLabel is a React ref for the <FormElement.Label />|

FormElement.Description

| Prop | Type | required | default | Description | | -------- | ---- | -------- | ------- | ---------------------------------------- | | children | node | false | null | Content for the form element description |

FormElement.Error

| Prop | Type | required | default | Description | | -------- | ------ | -------- | ----------------------- | ---------------------------- | | children | node | false | null | Content of the error message | | size | custom | false | Error.types.size.MEDIUM | |

FormElement.Instructions

| Prop | Type | required | default | Description | | -------- | ---- | -------- | ------- | ----------------------------------------- | | children | node | false | null | Content for the form element instructions |

FormElement.Label

| Prop | Type | required | default | Description | | ---------------- | ----------------------------------------------------------------------------------------------------------- | -------- | ----------------------- | ----------------------------------------------------------- | | children | node | true | - | content for the label | | help | node | false | null | Help indicator | | helpA11yText | string | false | null | Aria label for icon button that triggers help popover | | isDisabled | bool | false | null | If the label should be dimmed and the help popover disabled | | isVisuallyHidden | bool | false | false | Should label be hidden | | helpAlign | [ Popover.types.align.TOP, Popover.types.align.RIGHT, Popover.types.align.BOTTOM, Popover.types.align.LEFT] | false | Popover.types.align.TOP | change tooltip alignment | | helpZIndex | number | false | null | zIndex for help tooltip |

FormElement.Layout

| Prop | Type | required | default | Description | | -------- | ---- | -------- | ------- | -------------------------- | | children | node | false | null | Content of the flex parent |

FormElement.Layout.LeftCol

| Prop | Type | required | default | Description | | -------- | --------------- | -------- | ------- | --------------------------------------------------------------------------- | | children | node | false | null | Content for left column flex child (typically the Label) | | width | [number,string] | false | "auto" | Width of the left column as number (pixels) or string (any CSS width value) |

FormElement.Layout.RightCol

| Prop | Type | required | default | Description | | -------- | ---- | -------- | ------- | --------------------------------------------------------------------------- | | children | node | false | null | Content for right column flex child (typically everything except the Label) |

Fieldset

Props are the same as FormElement but hasFieldSet=true.

Usage

The <L10n /> component is a required context provider that must wrap the <FormElement /> (or your application) for proper localization.

Using with <Input />

import Input from "@paprika/input";
import FormElement from "@paprika/form-element";

const { Label, Content } = FormElement;

<FormElement>
  <Label>First Name</Label>
  <Content>
    {a11yProps => (
      <Input
        onChange={handleChange}
        value={value}
        {...a11yProps}
      />
    )}
  </Content>
</FormElement>

Using with help popover, <Instructions />, <Description />, and <Error />

Best practices for laying out supporting content for a form input is to follow this order:

• <Label /> first.
• <Instructions /> above the input field contained in <Content />.
• <Description /> or <Error /> shown below input field (but do not render both at the same time).

Note: the <Error /> component will render null if its children is falsey.

import Input from "@paprika/input";
import FormElement from "@paprika/form-element";

const { Label, Content, Instructions, Description, Error } = FormElement;
const errorMsg = "There was an error.";

<FormElement>
  <Label help="Help text">Field label</Label>
  <Instructions>Instruction text</Instructions>
  <Content>
    {a11yProps => (
      <Input hasError={Boolean(errorMsg)} {...a11yProps} />
    )}
  </Content>
  {errorMsg 
    ? <Error>{errorMsg}</Error> 
    : <Description>Description text</Description>
  }
</FormElement>

Using <Fieldset /> with <Checkbox />

Since a group of <Checkbox /> or <Radio /> components consist of multiple inputs, each with their own <label>, then need to be wrapped in a <fieldset> element with a <legend> element as a common label. This is the same for any group of form inputs that need to be grouped under a common label.

For this purpose, the <Fieldset /> component can be used. It is provided as a named import from the same @paprika/form-element package.

The <Fieldset /> component has all the same subcomponents as the <FormElement /> – it actually is just a <FormElement /> with the hasFieldSet prop set to true.

import DatePicker from "@paprika/checkbox";
import { Fieldset } from "@paprika/form-element";

const { Label, Content, Error } = Fieldset;

<Fieldset>
  <Label>Select Options</Label>
  <Content>
    {a11yProps => (
      <>
        <Checkbox onChange={handleChange}>
          <Checkbox.Input {...a11yProps} />
          Cheese
        </Checkbox>
        <Checkbox onChange={handleChange}>
          <Checkbox.Input {...a11yProps} />
          Meat
        </Checkbox>
        <Checkbox onChange={handleChange}>
          <Checkbox.Input {...a11yProps} />
          Mushrooms
        </Checkbox>
      </>
    )}
  </Content>
  <Error>{errorMsg}</Error>
</Fieldset>

Links

• Storybook Showcase
• GitHub source code
• Create GitHub issue
• CHANGELOG