Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/zendeskgarden/website/llms.txt

Use this file to discover all available pages before exploring further.

Package: @zendeskgarden/react-forms 
import { Field, Checkbox, Fieldset } from '@zendeskgarden/react-forms';

​
When to use it

  • To let users compare options from a list and select all, any, or none of those items.
  • To turn a single option on or off.
For mutually exclusive choices, use Radio instead. To activate an option with immediate effect, use Toggle instead.

​
Basic usage

A Checkbox label is part of its touch target. 
import React, { useState } from 'react';
import { Field, Checkbox, Fieldset } from '@zendeskgarden/react-forms';

const Example = () => {
  const [pest, setPest] = useState(true);
  const [light, setLight] = useState(false);
  const [drought, setDrought] = useState(false);

  return (
    <Fieldset>
      <Fieldset.Legend>Plant preference</Fieldset.Legend>
      <Field>
        <Checkbox checked={pest} onChange={() => setPest(!pest)}>
          <Field.Label>Pest resistant</Field.Label>
        </Checkbox>
      </Field>
      <Field>
        <Checkbox checked={light} onChange={() => setLight(!light)}>
          <Field.Label>Needs direct light</Field.Label>
        </Checkbox>
      </Field>
      <Field>
        <Checkbox checked={drought} onChange={() => setDrought(!drought)}>
          <Field.Label>Drought-tolerant</Field.Label>
        </Checkbox>
      </Field>
    </Fieldset>
  );
};

export default Example;

​
Hint text

Use Field.Hint inside the Checkbox to add more context to the label. 
import React from 'react';
import { Field, Checkbox } from '@zendeskgarden/react-forms';

const Example = () => (
  <Field>
    <Checkbox defaultChecked>
      <Field.Label>Pest resistant</Field.Label>
      <Field.Hint>Safe for outdoor planting beds</Field.Hint>
    </Checkbox>
  </Field>
);

export default Example;

​
Indeterminate state

When child checkboxes have mixed states, set indeterminate on the parent checkbox to display a dash indicator. 
import React, { useReducer } from 'react';
import { Field, Checkbox } from '@zendeskgarden/react-forms';

const initialState = { pest: true, light: false };

const reducer = (state: typeof initialState, action: { type: string }) => {
  switch (action.type) {
    case 'all':   return { pest: true, light: true };
    case 'none':  return { pest: false, light: false };
    case 'pest':  return { ...state, pest: !state.pest };
    case 'light': return { ...state, light: !state.light };
    default:      return state;
  }
};

const Example = () => {
  const [state, dispatch] = useReducer(reducer, initialState);
  const { pest, light } = state;

  const allChecked = pest && light;
  const someChecked = pest || light;

  return (
    <>
      <Field>
        <Checkbox
          checked={allChecked}
          indeterminate={someChecked && !allChecked}
          onChange={() => dispatch({ type: allChecked ? 'none' : 'all' })}
        >
          <Field.Label>Outdoor readiness</Field.Label>
        </Checkbox>
      </Field>
      <Field style={{ marginLeft: 24 }}>
        <Checkbox checked={pest} onChange={() => dispatch({ type: 'pest' })}>
          <Field.Label isRegular>Pest resistant</Field.Label>
        </Checkbox>
      </Field>
      <Field style={{ marginLeft: 24 }}>
        <Checkbox checked={light} onChange={() => dispatch({ type: 'light' })}>
          <Field.Label isRegular>Needs direct light</Field.Label>
        </Checkbox>
      </Field>
    </>
  );
};

export default Example;

​
Validation states

Show success, warning, or error messages using Field.Message below the Checkbox. 
import React from 'react';
import { Field, Checkbox } from '@zendeskgarden/react-forms';

const Example = () => (
  <>
    <Field>
      <Checkbox defaultChecked>
        <Field.Label>Pest resistant</Field.Label>
      </Checkbox>
      <Field.Message validation="success">Safe for outdoor beds</Field.Message>
    </Field>
    <Field>
      <Checkbox>
        <Field.Label>Needs direct light</Field.Label>
      </Checkbox>
      <Field.Message validation="warning">Requires 4 hours of sun per day</Field.Message>
    </Field>
    <Field>
      <Checkbox>
        <Field.Label>Drought-tolerant</Field.Label>
      </Checkbox>
      <Field.Message validation="error">Not appropriate for greenhouse</Field.Message>
    </Field>
  </>
);

export default Example;

​
Component structure

<Field>
  <Checkbox>
    <Field.Label />
    <Field.Hint />
  </Checkbox>
  <Field.Message />
</Field>
Group related checkboxes in a Fieldset: 
<Fieldset>
  <Fieldset.Legend />
  <Field>
    <Checkbox>
      <Field.Label />
    </Checkbox>
  </Field>
  {/* more Field + Checkbox items */}
</Fieldset>

​
API reference

​
Field

Wraps a Checkbox and its label, hint, and message. Associates child elements for accessibility.

​
Field.Label

Renders a <label> associated with the Checkbox. Nest inside Checkbox.
​
body.isRegular
boolean
Renders label text at regular font weight instead of bold (default).
​
body.hidden
boolean
Visually hides the label while keeping it accessible to screen readers.

​
Field.Hint

Renders supplementary hint text. Nest inside Checkbox.

​
Field.Message

Renders a validation message below the Checkbox. Nest inside Field.
​
body.validation
'success' | 'warning' | 'error'
Determines the icon and color of the message.

​
Checkbox

A styled <input type="checkbox">. Nest inside Field. Place Field.Label and Field.Hint as children.
​
body.checked
boolean
Controls the checked state (controlled usage).
​
body.defaultChecked
boolean
Sets the initial checked state (uncontrolled usage).
​
body.indeterminate
boolean
Displays a dash indicator to signal a mixed child state.
​
body.disabled
boolean
Prevents user interaction and removes the element from the tab order.
​
body.onChange
(event: React.ChangeEvent<HTMLInputElement>) => void
Called when the checked state changes.

​
Fieldset

Provides styles for grouping related Field + Checkbox components. Wrap with a Fieldset.Legend for an accessible group label.

​
Fieldset.Legend

Renders a <legend> inside a Fieldset.