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, Toggle } from '@zendeskgarden/react-forms';

​
When to use it

  • To see or compare the results of a settings change.
  • To activate a mode such as dark mode that takes immediate effect.
To let users select from a list of settings, use Checkboxes instead.

​
Basic usage

A Toggle’s label is part of its touch target. Nest Field.Label inside the Toggle component. 
import React from 'react';
import { Field, Toggle } from '@zendeskgarden/react-forms';

const Example = () => (
  <Field>
    <Toggle>
      <Field.Label>Show flowers</Field.Label>
    </Toggle>
  </Field>
);

export default Example;

​
Checked state

Control the toggle state with checked and onChange. 
import React, { useState } from 'react';
import { Field, Toggle } from '@zendeskgarden/react-forms';

const Example = () => {
  const [isOn, setIsOn] = useState(false);

  return (
    <Field>
      <Toggle checked={isOn} onChange={() => setIsOn(!isOn)}>
        <Field.Label>Dark mode</Field.Label>
      </Toggle>
    </Field>
  );
};

export default Example;

​
Hint text

Use Field.Hint inside Toggle to add supporting context. 
import React from 'react';
import { Field, Toggle } from '@zendeskgarden/react-forms';

const Example = () => (
  <Field>
    <Toggle>
      <Field.Label>Notifications</Field.Label>
      <Field.Hint>Receive alerts when plants need watering</Field.Hint>
    </Toggle>
  </Field>
);

export default Example;

​
Disabled state

A disabled Toggle prevents user interaction, does not appear in the tab order, and cannot receive focus. 
import React from 'react';
import { Field, Toggle } from '@zendeskgarden/react-forms';

const Example = () => (
  <Field>
    <Toggle disabled>
      <Field.Label>Auto-watering</Field.Label>
    </Toggle>
  </Field>
);

export default Example;

​
Validation states

Use Field.Message inside Toggle to display success, warning, or error messages. 
import React from 'react';
import { Field, Toggle } from '@zendeskgarden/react-forms';

const Example = () => (
  <>
    <Field>
      <Toggle>
        <Field.Label>Show tulips</Field.Label>
        <Field.Message validation="success">Tulips are blooming</Field.Message>
      </Toggle>
    </Field>
    <Field>
      <Toggle>
        <Field.Label>Show marigolds</Field.Label>
        <Field.Message validation="warning">It's not the right season for marigolds</Field.Message>
      </Toggle>
    </Field>
    <Field>
      <Toggle>
        <Field.Label>Show roses</Field.Label>
        <Field.Message validation="error">There are no roses available</Field.Message>
      </Toggle>
    </Field>
  </>
);

export default Example;

​
Component structure

<Field>
  <Toggle>
    <Field.Label />
    <Field.Hint />
    <Field.Message />
  </Toggle>
</Field>

​
API reference

​
Field

Wraps the Toggle and its associated label, hint, and message. Provides accessibility attributes.

​
Field.Label

Renders a <label> associated with the Toggle. Nest inside Toggle.
​
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 Toggle.

​
Field.Message

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

​
Toggle

A styled toggle switch backed by <input type="checkbox">. Nest inside Field. Place Field.Label, Field.Hint, and Field.Message as children.
​
body.checked
boolean
Controls the on/off state (controlled usage).
​
body.defaultChecked
boolean
Sets the initial on/off state (uncontrolled usage).
​
body.disabled
boolean
Prevents user interaction and removes the element from the tab order.
​
body.onChange
(event: React.ChangeEvent<HTMLInputElement>) => void
Called when the toggle state changes.