grommet
components

FormField

a single field in a form

Storybook
CodeSandbox

Props

a11yTitle

Custom label to be used by screen readers. Should only be provided if FormField has no children. When a11yTitle is provided an aria-label will be added to the element if it has no children.

"a user friendly label for screen readers"

component

The component to insert in the FormField. Grommet will add update the form values when this field changes. Any additional properties (such as initial value) you pass to FormField will be forwarded to this component. The component may be custom as long it supports the properties of name, value, onChange (event => {}), while event has either event.value or event.target.value.

"function""object"

contentProps

Any valid Box property. These properties are applied to the FormField contents container and will override properties from the theme.

"object"

disabled

Whether the field should look disabled.
truefalse

error

Any error text describing issues with the field's value
"string""node"

help

Any help text describing how the field works
"string""node"

htmlFor

The id of the input element contained in this field
"string"

info

Any informational text regarding the field's value
"string""node"

label

A short label describing the field
"string""node"

margin

The amount of margin around the component. An object can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.

"xsmall"
"small"
"medium"
"large"
"xlarge"
{
  "vertical": "...",
  "horizontal": "...",
  "top": "...",
  "bottom": "...",
  "left": "...",
  "right": "..."
}

name

The name of the value data when in a Form and the name of the input field.

"string"

pad

Whether to add padding to align with the padding of TextInput.
truefalse

required

Whether the field is required.
truefalse

validate

Validation rule when used within a grommet Form. Provide an object with a regular expression, a function, or an array of these. If a function is provided, it will be called with two arguments, the value for this field and the entire value object. This permits validation to encompass multiple fields. The function should return a string message describing the validation issue, if any, or an object with 'message' and 'status' properties.

"function"
{
regexp:
"new RegExp(...),"
message:
"string""node,"
status:
"error""info"
}
[
"function"
{
regexp:
"new RegExp(...),"
message:
"string""node,"
status:
"error""info"
}
]

Theme

formField.border.color

The border color.
"border"

formField.border.error.color

The border color of the error.
{
  "dark": "white",
  "light": "status-critical"
}

formField.border.position

The border position.
"inner"

formField.border.side

The border side of the FormField.
"bottom"

formField.content.margin

The margin of the FormField content.
object

formField.content.pad

The pad of the FormField content.
"small"

formField.disabled.background.color

The color of the FormField background when it is disabled.
"status-disabled"

formField.disabled.background.opacity

The opacity of the FormField background when it is disabled.
"medium"

formField.disabled.border.color

The color of the FormField border when it is disabled.
string | {'dark': string, 'light': string}

formField.disabled.label.color

The color of the FormField label when it is disabled.
string | {'dark': string, 'light': string}

formField.error.background.color

The color of the FormField background when there is an error.
string | {'dark': string, 'light': string}

formField.error.background.opacity

The opacity of the FormField background when there is an error.
string | boolean | number

formField.error.color

The color of the FormField error.
"status-critical"

formField.error.container

Any valid Box props for the container surrounding the error message and icon.

object

formField.error.icon

An icon placed in a row with the error message.
React.Element

formField.error.size

The size of the error message to be displayed. The default size is medium.

string

formField.error.size.xsmall

The size of a 'xsmall' error message.
string

formField.error.size.small

The size of a 'small' error message.
string

formField.error.size.medium

The size of a 'medium' error message.
string

formField.error.size.large

The size of a 'large' error message.
string

formField.error.size.xlarge

The size of a 'xlarge' error message.
string

formField.info.container

Any valid Box props for the container surrounding the info message and icon.

object

formField.info.icon

An icon placed in a row with the info message.
React.Element

formField.error.margin

The margin used for the FormField error.
{
  "vertical": "xsmall",
  "horizontal": "small"
}

formField.focus.background.color

The color of the FormField background when it is in focus.
string | {'dark': string, 'light': string}

formField.focus.border.color

The color of the FormField border when it is in focus.
string | {'dark': string, 'light': string}

formField.extend

Any additional style for FormField.
"any CSS"
(props) => {}

formField.help.color

The color of the FormField help.
"dark-3"

formField.help.margin

The margin for the FormField help.
{"start": "small"}

formField.info.color

The color of the FormField info.
"text-xweak"

formField.info.margin

The margin used for the FormField info.
{
  "vertical": "xsmall",
  "horizontal": "small"
}

formField.label

Any props of Text that will be applied on the FormField label.
{
  "margin": {
    "vertical": "xsmall",
    "horizontal": "small"
  }
}

formField.label.margin

The margin for the FormField label.
{
  "vertical": "xsmall",
  "horizontal": "small"
}

formField.label.requiredIndicator

Whether an asterisk (*) indicating that an input is required should be displayed adjacent to the FormField's label. If providing a custom element, for accessibility it is recommended that you include an a11yTitle of "required" to assist screen readers. If using "true", the a11yTitle is automatically applied.

boolean | element | string

formField.margin

The margin of FormField.
{"bottom": "small"}

formField.round

The rounding of the FormField.
boolean | string | object

global.borderSize

The possible border sizes for FormField.
{
  "xsmall": "1px",
  "small": "2px",
  "medium": "4px",
  "large": "12px",
  "xlarge": "24px"
}