npm package: @paprika/form-element
Description: FormElement component displays a user input field
Author: @paprika
Latest version: 7.0.4

<!-- start: Autogenerated - do not modify -->

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

<!-- end: Autogenerated - do not modify -->
<!-- content -->

<!-- generated manually until readme script is updated -->

### 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 />`

<!-- prettier-ignore -->
```jsx
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.

<!-- prettier-ignore -->
```jsx
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`.

<!-- prettier-ignore -->
```jsx
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>
```

<!-- eoContent -->

## Links

- [Storybook Showcase](https://paprika.highbond.com/?path=/story/forms-formelement--showcase)
- [GitHub source code](https://github.com/acl-services/paprika/tree/master/packages/FormElement/src)
- [Create GitHub issue](https://github.com/acl-services/paprika/issues/new?label=[]&title=@paprika/form-element%20[help]:%20your%20short%20description&body=%0A%23%20Help%20wanted%0A%0A%23%23%20Please%20write%20your%20question.%0A*A%20clear%20and%20concise%20description%20of%20what%20the%20question%20is*%0A%0A%23%23%20Additional%20context%0A*Add%20any%20other%20context%20or%20screenshots%20about%20your%20question%20here.*%0A)
- [CHANGELOG](https://github.com/acl-services/paprika/tree/master/packages/FormElement/CHANGELOG.md)