@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||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|

Fieldset

| 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.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