This is version 4 beta of Forma 36Go back to last stable version 3
Forma 36

FormControl

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

Table of contents

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

Example with invalid input

Example of Select component with FormControl

Example of Radio Group component with FormControl

Example of Checkbox Group component with FormControl

Example with character count

Props

FormControl

NameRequiredDefaultTypeDescription
idstring
inputValuestringvalue from text input and textarea to used for counting characters
isDisabled
false
true
If `true` set the form control to the disabled state.
isInvalid
false
true
If `true` set the form control to the invalid state.
isReadOnly
false
true
If `true` set the form control to the read only state.
isRequired
false
true
If `true` set the form control to be required.
marginSpacingsets margin to one of the corresponding spacing tokens
marginBottomSpacingsets margin-bottom to one of the corresponding spacing tokens
marginLeftSpacingsets margin-left to one of the corresponding spacing tokens
marginRightSpacingsets margin-right to one of the corresponding spacing tokens
marginTopSpacingsets margin-top to one of the corresponding spacing tokens
maxLengthnumberMax length of characters used for the text input and textarea
setInputValueDispatch<SetStateAction<string>>Set input value function
setMaxLengthDispatch<SetStateAction<number>>Set max length function
childrenrequiredReactNode
asHTML Tag or React Component, e.g. div, span, etc.
classNamestringCSS class to be appended to the root element
styleCSSPropertiesAccepts a JavaScript object with camelCased properties rather than a CSS string
testIdstringA [data-test-id] attribute used for testing purposes

Label

NameRequiredDefaultTypeDescription
isRequiredfalse
false
true
Whether or not the associated input element is required
marginSpacingsets margin to one of the corresponding spacing tokens
marginBottomSpacingsets margin-bottom to one of the corresponding spacing tokens
marginLeftSpacingsets margin-left to one of the corresponding spacing tokens
marginRightSpacingsets margin-right to one of the corresponding spacing tokens
marginTopSpacingsets margin-top to one of the corresponding spacing tokens
requiredText"required"stringCustom text to show in parentheses that gets rendered if the associated input is required
childrenrequiredReactNodeLabel value to show
aslabelHTML Tag or React Component, e.g. div, span, etc.Defines how the element will be rendered
classNamestringCSS class to be appended to the root element
styleCSSPropertiesAccepts a JavaScript object with camelCased properties rather than a CSS string
testIdstringA [data-test-id] attribute used for testing purposes

HelpText

NameRequiredDefaultTypeDescription
marginSpacingsets margin to one of the corresponding spacing tokens
marginBottomSpacingsets margin-bottom to one of the corresponding spacing tokens
marginLeftSpacingsets margin-left to one of the corresponding spacing tokens
marginRightSpacingsets margin-right to one of the corresponding spacing tokens
marginTopSpacingsets margin-top to one of the corresponding spacing tokens
childrenrequiredReactNode
classNamestringCSS class to be appended to the root element
styleCSSPropertiesAccepts a JavaScript object with camelCased properties rather than a CSS string
testIdcf-ui-help-textstringA [data-test-id] attribute used for testing purposes

ValidationMessage

NameRequiredDefaultTypeDescription
marginSpacingsets margin to one of the corresponding spacing tokens
marginBottomSpacingsets margin-bottom to one of the corresponding spacing tokens
marginLeftSpacingsets margin-left to one of the corresponding spacing tokens
marginRightSpacingsets margin-right to one of the corresponding spacing tokens
marginTopSpacingsets margin-top to one of the corresponding spacing tokens
childrenrequiredReactNode
classNamestringCSS class to be appended to the root element
styleCSSPropertiesAccepts a JavaScript object with camelCased properties rather than a CSS string
testIdcf-ui-validation-messagestringA [data-test-id] attribute used for testing purposes