FormControl

FormControl is a wrapper component to enhance layout with input label, help text, counter or validation message.

How to use FormControl

• FormControl provides context to form elements: isRequired, isDisabled, isInvalid, isReadOnly
• Compound components of FormControl are: Label, HelpText, ValidationMessage, Counter. These components provide additional visual context and hints for users.
• For more information on how to use FormControl in Form, check the guide for Form.

Design guidelines

To uphold a consistent look and experience for your application, we recommend following the same design layout guidelines for all inputs:

• Label is a required element that all your inputs should have to pass the a11y requirements. It should be placed on top of the input, so it would be first in your HTML structure.
• An input component should follow the label
• HelpText should appear under the input, when you need to display some additional information to the user
• ValidationMessage should be appearing directly under the input or under HelpText if displayed, to clearly indicate that it is invalid
• TextInput and Textarea components can have an option of counting characters. In that case, we recommend aligning HelpText and Counter by using the Flex component and placed them right below the input. Have a look on the example over here

Usage examples

Basic example

<FormControl isRequired>
  <FormControl.Label>Name</FormControl.Label>
  <TextInput />
  <FormControl.HelpText>Please enter your first name</FormControl.HelpText>
</FormControl>
<FormControl isRequired>
  <FormControl.Label>Name</FormControl.Label>
  <TextInput />
  <FormControl.HelpText>Please enter your first name</FormControl.HelpText>
</FormControl>
Hide source

Example with invalid input

<FormControl isInvalid>
  <FormControl.Label>Name</FormControl.Label>
  <TextInput />
  <FormControl.ValidationMessage>Error</FormControl.ValidationMessage>
  <FormControl.HelpText>Please enter your first name</FormControl.HelpText>
</FormControl>
<FormControl isInvalid>
  <FormControl.Label>Name</FormControl.Label>
  <TextInput />
  <FormControl.ValidationMessage>Error</FormControl.ValidationMessage>
  <FormControl.HelpText>Please enter your first name</FormControl.HelpText>
</FormControl>
Hide source

Example of Select component with FormControl

<FormControl>
  <FormControl.Label>Name</FormControl.Label>
  <Select defaultValue="optionTwo">
    <Select.Option value="optionOne">Option 1</Select.Option>
    <Select.Option value="optionTwo">Option 2</Select.Option>
  </Select>
  <FormControl.HelpText>Please select an option</FormControl.HelpText>
</FormControl>
<FormControl>
  <FormControl.Label>Name</FormControl.Label>
  <Select defaultValue="optionTwo">
    <Select.Option value="optionOne">Option 1</Select.Option>
    <Select.Option value="optionTwo">Option 2</Select.Option>
  </Select>
  <FormControl.HelpText>Please select an option</FormControl.HelpText>
</FormControl>
Hide source

Example of Radio Group component with FormControl

<FormControl as="fieldset">
  <FormControl.Label as="legend">Radio group options</FormControl.Label>
  <Radio.Group name="radio-options" defaultValue="option 1">
    <Radio value="option 1" id="option-1" helpText="Help text for option 1">
      Option 1
    </Radio>
    <Radio value="option 2" id="option-2" helpText="Help text for option 2">
      Option 2
    </Radio>
  </Radio.Group>
  <FormControl.HelpText>Please, select an option</FormControl.HelpText>
</FormControl>
<FormControl as="fieldset">
  <FormControl.Label as="legend">Radio group options</FormControl.Label>
  <Radio.Group name="radio-options" defaultValue="option 1">
    <Radio value="option 1" id="option-1" helpText="Help text for option 1">
      Option 1
    </Radio>
    <Radio value="option 2" id="option-2" helpText="Help text for option 2">
      Option 2
    </Radio>
  </Radio.Group>
  <FormControl.HelpText>Please, select an option</FormControl.HelpText>
</FormControl>
Hide source

Example of Checkbox Group component with FormControl

<FormControl as="fieldset" isRequired>
  <FormControl.Label as="legend">Checkbox group options</FormControl.Label>
  <Checkbox.Group name="checkbox-options">
    <Checkbox value="option 1" id="option-1" helpText="Some help text">
      Option 1
    </Checkbox>
    <Checkbox value="option 2" id="option-2" helpText="Another help text">
      Option 2
    </Checkbox>
  </Checkbox.Group>
  <FormControl.HelpText>
    Please, select at least one option
  </FormControl.HelpText>
</FormControl>
<FormControl as="fieldset" isRequired>
  <FormControl.Label as="legend">Checkbox group options</FormControl.Label>
  <Checkbox.Group name="checkbox-options">
    <Checkbox value="option 1" id="option-1" helpText="Some help text">
      Option 1
    </Checkbox>
    <Checkbox value="option 2" id="option-2" helpText="Another help text">
      Option 2
    </Checkbox>
  </Checkbox.Group>
  <FormControl.HelpText>
    Please, select at least one option
  </FormControl.HelpText>
</FormControl>
Hide source

Example with character count

<FormControl>
  <FormControl.Label isRequired>Name</FormControl.Label>
  <TextInput maxLength={8} />
  <Flex justifyContent="space-between">
    <FormControl.HelpText>
      Name should be no longer than 8 characters
    </FormControl.HelpText>
    <FormControl.Counter />
  </Flex>
</FormControl>
<FormControl>
  <FormControl.Label isRequired>Name</FormControl.Label>
  <TextInput maxLength={8} />
  <Flex justifyContent="space-between">
    <FormControl.HelpText>
      Name should be no longer than 8 characters
    </FormControl.HelpText>
    <FormControl.Counter />
  </Flex>
</FormControl>
Hide source

Props

FormControl

• Name

  children(required)

  ReactNode
• Name

  as

  HTML Tag or React Component (e.g. div, span, etc)
• Name

  className

  Description

  CSS class to be appended to the root element

  string
• Name

  id

  string
• Name

  inputValue

  Description

  value from text input and textarea to used for counting characters

  string
• Name

  isDisabled

  Description

  If `true` set the form control to the disabled state.

  false

  true
• Name

  isInvalid

  Description

  If `true` set the form control to the invalid state.

  false

  true
• Name

  isReadOnly

  Description

  If `true` set the form control to the read only state.

  false

  true
• Name

  isRequired

  Description

  If `true` set the form control to be required.

  false

  true
• Name

  margin

  Description

  sets margin to one of the corresponding spacing tokens

  "none"

  "spacing2Xs"

  "spacingXs"

  "spacingS"

  "spacingM"

  "spacingL"

  "spacingXl"

  "spacing2Xl"

  "spacing3Xl"

  "spacing4Xl"
• Name

  marginBottom

  Description

  sets margin-bottom to one of the corresponding spacing tokens

  "none"

  "spacing2Xs"

  "spacingXs"

  "spacingS"

  "spacingM"

  "spacingL"

  "spacingXl"

  "spacing2Xl"

  "spacing3Xl"

  "spacing4Xl"
• Name

  marginLeft

  Description

  sets margin-left to one of the corresponding spacing tokens

  "none"

  "spacing2Xs"

  "spacingXs"

  "spacingS"

  "spacingM"

  "spacingL"

  "spacingXl"

  "spacing2Xl"

  "spacing3Xl"

  "spacing4Xl"
• Name

  marginRight

  Description

  sets margin-right to one of the corresponding spacing tokens

  "none"

  "spacing2Xs"

  "spacingXs"

  "spacingS"

  "spacingM"

  "spacingL"

  "spacingXl"

  "spacing2Xl"

  "spacing3Xl"

  "spacing4Xl"
• Name

  marginTop

  Description

  sets margin-top to one of the corresponding spacing tokens

  "none"

  "spacing2Xs"

  "spacingXs"

  "spacingS"

  "spacingM"

  "spacingL"

  "spacingXl"

  "spacing2Xl"

  "spacing3Xl"

  "spacing4Xl"
• Name

  maxLength

  Description

  Max length of characters used for the text input and textarea

  number
• Name

  setInputValue

  Description

  Set input value function

  Dispatch<SetStateAction<string>>
• Name

  setMaxLength

  Description

  Set max length function

  Dispatch<SetStateAction<number>>
• Name

  testId

  Description

  A [data-test-id] attribute used for testing purposes

  string

Label

HelpText

ValidationMessage