@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.
<Input />
Using with 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>
help
popover, <Instructions />
, <Description />
, and <Error />
Using with 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>
<Fieldset />
with <Checkbox />
Using 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>