CheckBox

a checkbox toggle control

Storybook

CodeSandbox

Github

Using Grommet for HPE?See CheckBox examples and guidance.

Props

a11yTitle

Custom label to be used by screen readers. When provided, an aria-label will be added to the element.

string

"a user friendly label for screen readers"

checked

Same as React <input checked={} />

boolean

true

false

children

Function that will be called to render the visual representation. It will be passed an object indicating whether the button is checked. It should return a react element.

function

'checked' and 'indeterminate' can be passed as arguments that would then return a react element.

({ checked, indeterminate }) => <Box ...>{...}</Box>

disabled

Same as React <input disabled={} />. Also adds a hidden input element with the same name so form submissions work.

boolean

true

false

fill

Whether the checkbox and label expand to fill all of the available width and/or height of their container.

boolean

true

false

id

The DOM id attribute value to use for the underlying <input /> element.

string

"a-dom-id"

indeterminate

Whether state is indeterminate. NOTE: This can only be used with non-toggle components

boolean

true

false

label

Label text to place next to the control. Can be used instead of a11yTitle to meet accessibility requirements

string

"enabled"

element

<Box>...</Box>

name

The DOM name attribute value to use for the underlying <input /> element.

string

"a-dom-name"

onChange

Function that will be called when the user clicks the check box. It will be passed a React event object. The current state can be accessed via event.target.checked. Same as React <input onChange={} />.

function

() => {}

pad

The amount of padding on the container surrounding the checkbox and its label.

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: "..."
}

reverse

Whether to show the label in front of the checkbox.

boolean

true

false

toggle

Whether to visualize it as a toggle switch.

boolean

true

false

React/DOM Properties

At its core, the CheckBox component is a regular <input> 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 input 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

checkBox.border.color

The border color when unchecked.

string

A hex, name, or rgb value.

"black"

object

An object with a color for dark and light modes.

{ dark: 'rgba(255, 255, 255, 0.5)', light: 'rgba(0, 0, 0, 0.15)' }

checkBox.border.width

The border width when unchecked.

string

"2px"

checkBox.check.extend

Any additional style for checked CheckBox.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

checkBox.check.radius

The radius of the checked icon.

string

"4px"

checkBox.check.thickness

The stroke width of the checked icon.

string

"4px"

checkBox.color

The stroke color for the CheckBox icon, and the border when checked.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

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

checkBox.extend

Any additional style for CheckBox.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

checkBox.gap

The right margin of the CheckBox to its label.

string

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

"none"

"xsmall"

"small"

"medium"

"large"

"xlarge"

"any CSS size"

checkBox.hover.border.color

The border color on hover.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

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

checkBox.hover.background.color

The background color of the Box surrounding the RadioButton when hovered over.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

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

checkBox.hover.extend

Any additional style for CheckBox hover.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

checkBox.icon.size

The size of the checked icon.

string

"18px"

checkBox.icon.extend

Any additional style for CheckBox icon.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

checkBox.icons.checked

The icon to use when checked.

element

<FormCheckmark />

checkBox.icons.indeterminate

The icon to use when indeterminate.

element

<FormCheckmark />

checkBox.label.align

How to align the checkbox and label.

string

"center"

checkBox.pad

The pad around the CheckBox and its label.

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: "..."
}

checkBox.size

The height and width used for the CheckBox icon.

string

"24px"

checkBox.toggle.background

The background color of the toggle.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

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

checkBox.toggle.color

The color of the toggle knob.

string

A hex, name, or rgb value.

"#d9d9d9"

object

An object with a color for dark and light modes.

{ dark: "#d9d9d9", light: "#d9d9d9" }

checkBox.toggle.extend

Any additional style for CheckBox toggle.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

checkBox.toggle.knob.extend

Any additional style for the CheckBox toggle knob.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

checkBox.toggle.radius

The border radius used for the toggle and the knob.

string

"24px"

checkBox.toggle.size

The width size of the toggle.

string

"48px"

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: "..."
}