FormField

a single field in a form

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.

string

"a user friendly label for screen readers"

component

The component to insert in the FormField. Grommet will 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.

object

TextArea

function

props => <input {...props} />

contentProps

Any valid Box property.

object

These properties are applied to the FormField contents container and will override properties from the theme.

{}

disabled

Whether the field should look disabled.

boolean

true

false

error

Any error text describing issues with the field's value.

string

"Text to call attention to an issue with this field"

node

{<Box>...</Box>}

help

Any help text describing how the field works.

string

"Text to help the user know what is possible"

node

<Box>...</Box>

htmlFor

The id of the input element contained in this field. If the input element is Select or SelectMultiple, append "__input" to the id.

string

"input-id"

If input is Select or SelectMultiple: "input-id__input"

info

Any informational text regarding the field's value.

string

"Additional information to give the user better context of the FormField."

node

<Box>...</Box>

label

A short label describing the field.

string

"label"

node

<Box>...</Box>

margin

The amount of margin around the component.

string

"none"

"xxsmall"

"xsmall"

"small"

"medium"

"large"

"xlarge"

object

Can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.


{
    vertical: "...",
    horizontal: "...",
    top: "...",
    bottom: "...",
    left: "...",
    right: "..."
}

name

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

NOTE: A name must be provided if using FormField's validate prop.

string

"name"

pad

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

boolean

true

false

required

Whether the field is required. If formField.requiredIndicator = true in your theme, passing indicator: false will not display the required indicator for the given field.

boolean

true

false

object

required={{ indicator: false }}

validate

Validation rule when used within a grommet Form. Provide an object with a regular expression, a function, or an array of these.

NOTE: In order to use validate, a name must first be provided to the FormField.

object

An object with max and (optionally) threshold can be used to implement a character counter.


{
  regexp: regular expression,
  message: "string" | node,
  status: "error" | "info"
}


{
  max: number,
  threshold: number,
}

function

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.

() => {}

array


[
  {
    regexp: regular expression,
    message: "string" | node,
    status: "error" | "info"
  },
  function
]

validateOn

When to perform validation

string

"blur"

"submit"

"change"

React/DOM Properties

At its core, the FormField component is a regular <div> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for div elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

Also, feel free to read about the types of React events available, or see how DOM attributes change in React. Working in tandem with Styled Components, you also have access to the as property.

Theme

formField.border.color

The border color.

string

A hex, name, or rgb value.

"border"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

formField.border.error.color

The border color of the error. Deprecated, use error.border.color instead.

string

A hex, name, or rgb value.

"status-critical"

object

An object with a color for dark and light modes.

{ dark: 'white', light: 'status-critical' }

formField.border.position

The border position.

string

"inner"

formField.border.side

The border side of the FormField.

string

"bottom"

formField.checkBox.pad

The CheckBox pad when wrapped in FormField.

string

T-shirt sizing based off the theme or a specific size in px, em, etc.

"none"

"xxsmall"

"xsmall"

"small"

"medium"

"large"

"xlarge"

"any CSS size"

object

An object can be specified to distinguish horizontal padding, vertical padding, and padding on a particular side.


{
  vertical: "...",
  horizontal: "...",
  top: "...",
  bottom: "...",
  left: "...",
  right: "...",
  start: "...",
  end: "..."
}

formField.content.margin

The margin of the FormField content.

string

"none"

"xxsmall"

"xsmall"

"small"

"medium"

"large"

"xlarge"

object

Can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.


{
    vertical: "...",
    horizontal: "...",
    top: "...",
    bottom: "...",
    left: "...",
    right: "..."
}

formField.content.pad

The pad of the FormField content.

string

T-shirt sizing based off the theme or a specific size in px, em, etc.

"none"

"xxsmall"

"xsmall"

"small"

"medium"

"large"

"xlarge"

"any CSS size"

object

An object can be specified to distinguish horizontal padding, vertical padding, and padding on a particular side.


{
  vertical: "...",
  horizontal: "...",
  top: "...",
  bottom: "...",
  left: "...",
  right: "...",
  start: "...",
  end: "..."
}

formField.disabled.background.color

The color of the FormField background when it is disabled.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

formField.disabled.background.opacity

The opacity of the FormField background when it is disabled.

boolean

true

false

string

"medium"

number

0.5

formField.disabled.border.color

The color of the FormField border when it is disabled.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

formField.disabled.label.color

The color of the FormField label when it is disabled.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

formField.disabled.help

The color of the FormField help label when it is disabled.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

formField.disabled.info

The color of the FormField info label when it is disabled.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

formField.error.background.color

The color of the FormField background when there is an error.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

formField.error.background.opacity

The opacity of the FormField background when there is an error.

boolean

true

false

string

"medium"

number

0.5

formField.error.border.color

The border color of the error.

string

A hex, name, or rgb value.

"status-critical"

object

An object with a color for dark and light modes.

{ dark: "white", light: "status-critical" },

formField.error.color

The color of the FormField error.

string

A hex, name, or rgb value.

"status-critical"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" },

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.

element

<Icon />

formField.error.size

The size of the error message to be displayed.

string

"medium"

formField.error.size.xsmall

The size of a 'xsmall' error message.

string

"12px"

formField.error.size.small

The size of a 'small' error message.

string

"14px"

formField.error.size.medium

The size of a 'medium' error message.

string

"18px"

formField.error.size.large

The size of a 'large' error message.

string

"22px"

formField.error.size.xlarge

The size of a 'xlarge' error message.

string

"26px"

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.

element

<Icon />

formField.error.margin

The margin used for the FormField error.

string

"small"

object

{ vertical: "xsmall", horizontal: "small" }

formField.focus.background.color

The color of the FormField background when it is in focus.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

formField.focus.border.color

The color of the FormField border when it is in focus.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

formField.focus.containerFocus

Whether the focus should be on the FormField container or the Input. When true, the FormField container will receive focus; when false, the Input field will receive focus.

boolean

true

false

formField.extend

Any additional style for FormField.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

formField.[inputname].extend

Any additional style for FormField container to style differently based on the type of child element (e.g., TextInput, TextArea, etc.)

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

formField.help.color

The color of the FormField help.

string

A hex, name, or rgb value.

"dark-3"

object

An object with a color for dark and light modes.

{ dark: "dark-3", light: "dark-3" }

formField.help.margin

The margin for the FormField help.

string

"small"

object

{ start: "small" }

formField.kind.label

Any props of Text that will be applied on the FormField kind label.

object


{
  size: 'large',
  color: 'black',
  margin: {
    vertical: "xsmall",
  }
}

formField.info.color

The color of the FormField info.

string

A hex, name, or rgb value.

"text-xweak"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" },

formField.info.margin

The margin used for the FormField info.

string

"small"

object

{ vertical: "xsmall", horizontal: "small" }

formField.label

Any props of Text that will be applied on the FormField label.

object


{
  margin: {
    vertical: "xsmall",
    horizontal: "small"
  }
}

formField.label.margin

The margin for the FormField label.

string

"small"

object

{ 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.

boolean

If using "true", the a11yTitle is automatically applied.

true

false

element

If providing a custom element, for accessibility it is recommended that you include an a11yTitle of "required" to assist screen readers.

<Box a11yTitle="required">...</Box>

string

"required"

formField.margin

The margin of FormField.

string

"small"

object

{ bottom: "small" }

formField.round

The rounding of the FormField.

boolean

true

false

string

"xsmall"

"small"

"medium"

"large"

"xlarge"

"full"

"any CSS size"

object

{ size: "...", corner: "..." }

where corner could be:

"top"

"left"

"bottom"

"right"

"top-left"

"top-right"

"bottom-left"

"bottom-right"

global.borderSize

The possible border sizes for FormField.

object


{
  xsmall: "1px",
  small: "2px",
  medium: "4px",
  large: "12px",
  xlarge: "24px",
}