Toggle Switch

<State initial={{value1: true, value2: false}}>
    {([state, setState]) => (
        <>
        <ToggleSwitch
            checked={state.value1}
            label="Toggle 1"
            name="Toggle1"
            onChange={() => setState(prev => ({...prev, value1: !state.value1}))}
        />
        <br />
        <br />
        <ToggleSwitch
            checked={state.value2}
            label="Toggle 2"
            name="Toggle2"
            onChange={() => setState(prev => ({...prev, value2: !state.value2}))}
        />
        </>
    )}
</State>

<State initial={{value1: true, value2: false}}>
    {([state, setState]) => (
        <>
        <ToggleSwitch
            checked={state.value1}
            label="Toggle 1"
            name="Toggle1"
            onChange={() => setState(prev => ({...prev, value1: !state.value1}))}
        />
        <br />
        <br />
        <ToggleSwitch
            checked={state.value2}
            label="Toggle 2"
            name="Toggle2"
            onChange={() => setState(prev => ({...prev, value2: !state.value2}))}
        />
        </>
    )}
</State>

Toggle Switch Labels

Toggle Switch labels are on the right side of the toggle element. They generally have two pieces: the action being taken, and the subject matter.

Label Help

Labels can have a help icon with a tooltip to provide additional context to a label.

Action Only

Sometimes it make sense for the toggle's subject to be separated from the toggle itself. This is useful in a list-context or if the subject is tied to a more complex UI component such as a Card, Table, or Page title.

Action Only With Cards

<State initial={{value1: true, value2: false}}>
    {([state, setState]) => (
        <>
        <Card
            sharp
            active={state.value1}
            raised={state.value1}
            onClick={() => setState(prev => ({...prev, value1: !state.value1}))}
        >
            <Stack alignItems='center'>
                <Stack.Item fill>
                    <BodyText size="large" bold>Report Form Widget</BodyText>
                    <BodyText subdued>Lorem ipsum dolar emit</BodyText>
                </Stack.Item>
                <Stack.Item>
                    <ToggleSwitch
                        checked={state.value1}
                        label="Toggle 1"
                        name="Toggle1"

                    />
                </Stack.Item>
            </Stack>
        </Card>
        <Card
            className="m-t-2"
            sharp
            active={state.value2}
            raised={state.value2}
            onClick={() => setState(prev => ({...prev, value2: !state.value2}))}
        >
            <Stack alignItems='center'>
                <Stack.Item fill>
                    <BodyText size="large" bold>Audit Inventory Widget</BodyText>
                    <BodyText subdued>Lorem ipsum dolar emit</BodyText>
                </Stack.Item>
                <Stack.Item>
                    <ToggleSwitch
                        checked={state.value2}
                        label="Toggle 2"
                        name="Toggle2"
                    />
                </Stack.Item>
            </Stack>
        </Card>
        </>
    )}
</State>

<State initial={{value1: true, value2: false}}>
    {([state, setState]) => (
        <>
        <Card
            sharp
            active={state.value1}
            raised={state.value1}
            onClick={() => setState(prev => ({...prev, value1: !state.value1}))}
        >
            <Stack alignItems='center'>
                <Stack.Item fill>
                    <BodyText size="large" bold>Report Form Widget</BodyText>
                    <BodyText subdued>Lorem ipsum dolar emit</BodyText>
                </Stack.Item>
                <Stack.Item>
                    <ToggleSwitch
                        checked={state.value1}
                        label="Toggle 1"
                        name="Toggle1"

                    />
                </Stack.Item>
            </Stack>
        </Card>
        <Card
            className="m-t-2"
            sharp
            active={state.value2}
            raised={state.value2}
            onClick={() => setState(prev => ({...prev, value2: !state.value2}))}
        >
            <Stack alignItems='center'>
                <Stack.Item fill>
                    <BodyText size="large" bold>Audit Inventory Widget</BodyText>
                    <BodyText subdued>Lorem ipsum dolar emit</BodyText>
                </Stack.Item>
                <Stack.Item>
                    <ToggleSwitch
                        checked={state.value2}
                        label="Toggle 2"
                        name="Toggle2"
                    />
                </Stack.Item>
            </Stack>
        </Card>
        </>
    )}
</State>

Action Only In a List

When scanning a set of options, it may make sense to separate the toggle's subject to the left. This can be done with caution: the user should be able to understand they are toggling the text to the left on or off.

<Form>
    <ToggleSwitch
        className="m-b-2 d-b"
        label="Show Technician Availability"
        name="Toggle-1"
        value="Test1"
    />
    <ToggleSwitch
        className="m-b-2 d-b"
        label="Show Job Audit"
        name="Toggle-1"
        value="Test1"
    />
    <ToggleSwitch
        className="m-b-2 d-b"
        label="Show Smart Estimates"
        name="Toggle-1"
        value="Test1"
    />
</Form>

<Form>
    <ToggleSwitch
        className="m-b-2 d-b"
        label="Show Technician Availability"
        name="Toggle-1"
        value="Test1"
    />
    <ToggleSwitch
        className="m-b-2 d-b"
        label="Show Job Audit"
        name="Toggle-1"
        value="Test1"
    />
    <ToggleSwitch
        className="m-b-2 d-b"
        label="Show Smart Estimates"
        name="Toggle-1"
        value="Test1"
    />
</Form>

<Stack alignItems="stretch">
    <Stack direction="column" justifyContent="space-between" className="flex-grow-1 m-r-4">
        <BodyText
            el="label"
            htmlFor="switch-id1"
        >
            Technician Availability
        </BodyText>
        <BodyText
            el="label"
            htmlFor="switch-id2"
        >
            Job Audit
        </BodyText>
        <BodyText
            el="label"
            htmlFor="switch-id3"
        >
            Smart Estimates
        </BodyText>
    </Stack>
    <Stack direction="column" justifyContent="space-between">
        <ToggleSwitch
            className="m-b-2"
            label="Enabled"
            name="Toggle-1"
            value="Test1"
            id="switch-id1"
        />
        <ToggleSwitch
            className="m-b-2"
            label="Enabled"
            name="Toggle-2"
            value="Test2"
            id="switch-id2"
        />
        <ToggleSwitch
            label="Enabled"
            name="Toggle-3"
            value="Test3"
            id="switch-id3"
        />
    </Stack>
</Stack>

<Stack alignItems="stretch">
    <Stack direction="column" justifyContent="space-between" className="flex-grow-1 m-r-4">
        <BodyText
            el="label"
            htmlFor="switch-id1"
        >
            Technician Availability
        </BodyText>
        <BodyText
            el="label"
            htmlFor="switch-id2"
        >
            Job Audit
        </BodyText>
        <BodyText
            el="label"
            htmlFor="switch-id3"
        >
            Smart Estimates
        </BodyText>
    </Stack>
    <Stack direction="column" justifyContent="space-between">
        <ToggleSwitch
            className="m-b-2"
            label="Enabled"
            name="Toggle-1"
            value="Test1"
            id="switch-id1"
        />
        <ToggleSwitch
            className="m-b-2"
            label="Enabled"
            name="Toggle-2"
            value="Test2"
            id="switch-id2"
        />
        <ToggleSwitch
            label="Enabled"
            name="Toggle-3"
            value="Test3"
            id="switch-id3"
        />
    </Stack>
</Stack>

No Label

A toggle switch can also have no label when the context of what it turns on or off can be clearly understood. A tooltip can also be applied to describe the toggle's current state.

<State initial={{value1: true, value2: false, value3: false}}>
    {([state, setState]) => (
        <Form className="example">
            <style>{`
                .example .field { margin-bottom: 24px !important; }
                .example .field > label { display: none !important; }
            `}</style>
            <Stack alignItems="center" spacing="1" className="m-b-3">
                <Input
                    defaultValue="Leia Doe"
                    disabled={!state.value1}
                />
                <Input
                    defaultValue="leia12345@email.com"
                    disabled={!state.value1}
                />
                <Input
                    defaultValue="(123) 456–7890"
                    disabled={!state.value1}
                />
                <Tooltip text={"Leia Doe account is " + (state.value1 ? "enabled" : "disabled")} direction="tl">
                    <ToggleSwitch
                        checked={state.value1}
                        onClick={() => setState(prev => ({...prev, value1: !state.value1}))}
                    />
                </Tooltip>
            </Stack>
            <Stack alignItems="center" spacing="1" className="m-b-3">
                <Input
                    defaultValue="Jane Spencer"
                    disabled={!state.value2}
                />
                <Input
                    defaultValue="janespencer@email.com"
                    disabled={!state.value2}
                />
                <Input
                    defaultValue="(555) 456–7890"
                    disabled={!state.value2}
                />
                <Tooltip text={"Jane Spencer account is " + (state.value2 ? "enabled" : "disabled")} direction="tl">
                    <ToggleSwitch
                        checked={state.value2}
                        onClick={() => setState(prev => ({...prev, value2: !state.value2}))}
                    />
                </Tooltip>
            </Stack>
            <Stack alignItems="center" spacing="1">
                <Input
                    defaultValue="Bob Smith"
                    disabled={!state.value3}
                />
                <Input
                    defaultValue="bob@email.com"
                    disabled={!state.value3}
                />
                <Input
                    defaultValue="(492) 451–1290"
                    disabled={!state.value3}
                />
                <Tooltip text={"Bob Smith account is " + (state.value3 ? "enabled" : "disabled")} direction="tl">
                    <ToggleSwitch
                        checked={state.value3}
                        onClick={() => setState(prev => ({...prev, value3: !state.value3}))}
                    />
                </Tooltip>
            </Stack>
        </Form>
    )}
</State>

<State initial={{value1: true, value2: false, value3: false}}>
    {([state, setState]) => (
        <Form className="example">
            <style>{`
                .example .field { margin-bottom: 24px !important; }
                .example .field > label { display: none !important; }
            `}</style>
            <Stack alignItems="center" spacing="1" className="m-b-3">
                <Input
                    defaultValue="Leia Doe"
                    disabled={!state.value1}
                />
                <Input
                    defaultValue="leia12345@email.com"
                    disabled={!state.value1}
                />
                <Input
                    defaultValue="(123) 456–7890"
                    disabled={!state.value1}
                />
                <Tooltip text={"Leia Doe account is " + (state.value1 ? "enabled" : "disabled")} direction="tl">
                    <ToggleSwitch
                        checked={state.value1}
                        onClick={() => setState(prev => ({...prev, value1: !state.value1}))}
                    />
                </Tooltip>
            </Stack>
            <Stack alignItems="center" spacing="1" className="m-b-3">
                <Input
                    defaultValue="Jane Spencer"
                    disabled={!state.value2}
                />
                <Input
                    defaultValue="janespencer@email.com"
                    disabled={!state.value2}
                />
                <Input
                    defaultValue="(555) 456–7890"
                    disabled={!state.value2}
                />
                <Tooltip text={"Jane Spencer account is " + (state.value2 ? "enabled" : "disabled")} direction="tl">
                    <ToggleSwitch
                        checked={state.value2}
                        onClick={() => setState(prev => ({...prev, value2: !state.value2}))}
                    />
                </Tooltip>
            </Stack>
            <Stack alignItems="center" spacing="1">
                <Input
                    defaultValue="Bob Smith"
                    disabled={!state.value3}
                />
                <Input
                    defaultValue="bob@email.com"
                    disabled={!state.value3}
                />
                <Input
                    defaultValue="(492) 451–1290"
                    disabled={!state.value3}
                />
                <Tooltip text={"Bob Smith account is " + (state.value3 ? "enabled" : "disabled")} direction="tl">
                    <ToggleSwitch
                        checked={state.value3}
                        onClick={() => setState(prev => ({...prev, value3: !state.value3}))}
                    />
                </Tooltip>
            </Stack>
        </Form>
    )}
</State>

Constant Labeling

The Toggle Switch label is always the same text. It describes what the "ON" state of the toggle is. The label should not switch based off the toggle's state.

<State initial={true}>
    {([state, setState]) => (
        <Form>
            <ToggleSwitch
                label={state ? "Active" : "Inactive" }
                name="Toggle-1"
                onChange={() => setState(!state)}
            />
        </Form>
    )}
</State>

<State initial={true}>
    {([state, setState]) => (
        <Form>
            <ToggleSwitch
                label={state ? "Active" : "Inactive" }
                name="Toggle-1"
                onChange={() => setState(!state)}
            />
        </Form>
    )}
</State>

Positive Wording

Labels in general should be positive. Since the label and toggle are generally thought of as turning something on, labels should reenforce this. Examples include “Show”, “Hide”, “Activate”, “Group [by]”, “Track”, and “Activate”. Negative labeling can be used with caution, if it makes sense to a user to perform a negative action.

Immediate Results

In general, toggle switches should provide immediate feedback that something has occurred.

<State initial={false}>
    {([unlocked, setUnlocked]) => (
        <Form>
            <ToggleSwitch
                checked={unlocked}
                label="Unlock Custom Name"
                name="Toggle-1"
                onChange={() => setUnlocked(!unlocked)}
            />
            <Form.Group widths="equal" className="p-t-3">
                <Form.Input label="First Name" defaultValue="Jane" placeholder="Leia" disabled={!unlocked} />
                <Form.Input label="Last Name" defaultValue="Doe" placeholder="Organa" disabled={!unlocked} />
            </Form.Group>
        </Form>
    )}
</State>

<State initial={false}>
    {([unlocked, setUnlocked]) => (
        <Form>
            <ToggleSwitch
                checked={unlocked}
                label="Unlock Custom Name"
                name="Toggle-1"
                onChange={() => setUnlocked(!unlocked)}
            />
            <Form.Group widths="equal" className="p-t-3">
                <Form.Input label="First Name" defaultValue="Jane" placeholder="Leia" disabled={!unlocked} />
                <Form.Input label="Last Name" defaultValue="Doe" placeholder="Organa" disabled={!unlocked} />
            </Form.Group>
        </Form>
    )}
</State>

Consider using a Checkbox when a button needs to be pressed in for the setting to take place.

<Form>
    <Form.Checkbox
        label="Show Option 1"
        name="Check-1"
    />
    <Form.Checkbox
        label="Show Option 2"
        name="Check-2"
    />
    <Form.Checkbox
        label="Show Option 3"
        name="Check-3"
    />
    <Form.Button full primary>Apply</Form.Button>
</Form>

<Form>
    <Form.Checkbox
        label="Show Option 1"
        name="Check-1"
    />
    <Form.Checkbox
        label="Show Option 2"
        name="Check-2"
    />
    <Form.Checkbox
        label="Show Option 3"
        name="Check-3"
    />
    <Form.Button full primary>Apply</Form.Button>
</Form>

<State initial={{value1: true, value2: false, value3: false}}>
    {([state, setState]) => (
        <Form>
            <Form.ToggleSwitch
                checked={state.value1}
                onChange={() => setState(prev => ({...prev, value1: !state.value1}))}
                label="Show Option 1"
            />
            <Form.ToggleSwitch
                checked={state.value2}
                onChange={() => setState(prev => ({...prev, value2: !state.value2}))}
                label="Show Option 2"
            />
            <Form.ToggleSwitch
                checked={state.value3}
                onChange={() => setState(prev => ({...prev, value3: !state.value3}))}
                label="Show Option 3"
            />
            <Form.Button full primary>Apply</Form.Button>
        </Form>
    )}
</State>

<State initial={{value1: true, value2: false, value3: false}}>
    {([state, setState]) => (
        <Form>
            <Form.ToggleSwitch
                checked={state.value1}
                onChange={() => setState(prev => ({...prev, value1: !state.value1}))}
                label="Show Option 1"
            />
            <Form.ToggleSwitch
                checked={state.value2}
                onChange={() => setState(prev => ({...prev, value2: !state.value2}))}
                label="Show Option 2"
            />
            <Form.ToggleSwitch
                checked={state.value3}
                onChange={() => setState(prev => ({...prev, value3: !state.value3}))}
                label="Show Option 3"
            />
            <Form.Button full primary>Apply</Form.Button>
        </Form>
    )}
</State>

In a form

A Toggle Switch can also be added into a Form component.

<Form>
    <Headline el="div" className="m-b-4">Add Contact</Headline>
    <Form.Group widths="equal">
        <Form.Input label="First Name" placeholder="Leia" />
        <Form.Input label="Last Name" placeholder="Organa" />
    </Form.Group>
    <State>
        {([planet, setPlanet]) => (
            <Form.Select
                label="Home Planet"
                placeholder="Choose Planet"
                options={[
                    {key:1, value: 1, text: 'Alderaan'},
                    {key:2, value: 2, text: 'Bespin'},
                    {key:3, value: 3, text: 'Coruscant'},
                    {key:4, value: 4, text: 'Dagobah'},
                    {key:5, value: 5, text: 'Hoth'},
                    {key:6, value: 6, text: 'Kashyyyk'},
                    {key:7, value: 7, text: 'Naboo',},
                    {key:8, value: 8, text: 'Tatooine'},
                    {key:9, value: 9, text: 'Yavin'},
                ]}
                onChange={(event, value) => setPlanet(value.value)}
                value={planet}
            />
        )}
    </State>
    <State initial={{disabled: true, duration: undefined}}>
        {([state, setState]) => (
            <>
            <Form.ToggleSwitch
                checked={!state.disabled}
                label="Track Tax Values"
                onChange={() => setState(prev => ({...prev, disabled: !state.disabled}))}
            />
            <Form.Group>
                <Form.Input disabled={state.disabled} label="Tax Rate" placeholder="8.45%" />
                <Form.Input disabled={state.disabled} label="Duration" placeholder="3" />
                <Form.Select
                    disabled={state.disabled}
                    label="Duration Units"
                    placeholder="Choose Units"
                    options={[
                        {key:1, value: 1, text: 'Days'},
                        {key:2, value: 2, text: 'Weeks'},
                        {key:3, value: 3, text: 'Months'}
                    ]}
                    onChange={(event, value) => setState(prev => ({...prev, duration: !value.value}))}
                    value={state.duration}
                />
            </Form.Group>
            </>
        )}
    </State>
</Form>

<Form>
    <Headline el="div" className="m-b-4">Add Contact</Headline>
    <Form.Group widths="equal">
        <Form.Input label="First Name" placeholder="Leia" />
        <Form.Input label="Last Name" placeholder="Organa" />
    </Form.Group>
    <State>
        {([planet, setPlanet]) => (
            <Form.Select
                label="Home Planet"
                placeholder="Choose Planet"
                options={[
                    {key:1, value: 1, text: 'Alderaan'},
                    {key:2, value: 2, text: 'Bespin'},
                    {key:3, value: 3, text: 'Coruscant'},
                    {key:4, value: 4, text: 'Dagobah'},
                    {key:5, value: 5, text: 'Hoth'},
                    {key:6, value: 6, text: 'Kashyyyk'},
                    {key:7, value: 7, text: 'Naboo',},
                    {key:8, value: 8, text: 'Tatooine'},
                    {key:9, value: 9, text: 'Yavin'},
                ]}
                onChange={(event, value) => setPlanet(value.value)}
                value={planet}
            />
        )}
    </State>
    <State initial={{disabled: true, duration: undefined}}>
        {([state, setState]) => (
            <>
            <Form.ToggleSwitch
                checked={!state.disabled}
                label="Track Tax Values"
                onChange={() => setState(prev => ({...prev, disabled: !state.disabled}))}
            />
            <Form.Group>
                <Form.Input disabled={state.disabled} label="Tax Rate" placeholder="8.45%" />
                <Form.Input disabled={state.disabled} label="Duration" placeholder="3" />
                <Form.Select
                    disabled={state.disabled}
                    label="Duration Units"
                    placeholder="Choose Units"
                    options={[
                        {key:1, value: 1, text: 'Days'},
                        {key:2, value: 2, text: 'Weeks'},
                        {key:3, value: 3, text: 'Months'}
                    ]}
                    onChange={(event, value) => setState(prev => ({...prev, duration: !value.value}))}
                    value={state.duration}
                />
            </Form.Group>
            </>
        )}
    </State>
</Form>

Disabled State

<div>
    <ToggleSwitch
        checked
        className="d-b m-b-2"
        label="Default On"
        name="Toggle-1"
        value="Test1"
    />
    <ToggleSwitch
        className="d-b m-b-4"
        label="Default Off"
        name="Toggle-1"
        value="Test1"
    />
    <ToggleSwitch
        checked
        className="d-b m-b-2"
        disabled
        label="Disabled On"
        name="Toggle-1"
        value="Test1"
    />
    <ToggleSwitch
        disabled
        label="Disabled Off"
        name="Toggle-1"
        value="Test1"
    />
</div>

<div>
    <ToggleSwitch
        checked
        className="d-b m-b-2"
        label="Default On"
        name="Toggle-1"
        value="Test1"
    />
    <ToggleSwitch
        className="d-b m-b-4"
        label="Default Off"
        name="Toggle-1"
        value="Test1"
    />
    <ToggleSwitch
        checked
        className="d-b m-b-2"
        disabled
        label="Disabled On"
        name="Toggle-1"
        value="Test1"
    />
    <ToggleSwitch
        disabled
        label="Disabled Off"
        name="Toggle-1"
        value="Test1"
    />
</div>

<State initial={{value1: true, value2: true, value3: true}}>
    {([state, setState]) => (
        <div>
            <BodyText className="m-b-2">Notification settings:</BodyText>
            <ToggleSwitch
                className="m-r-4"
                checked={state.value1}
                label="Enable all notifications"
                onChange={() => setState(prev => ({...prev, value1: !state.value1}))}
            />
            <ToggleSwitch
                className="m-r-4"
                checked={state.value2 || state.value1}
                disabled={state.value1}
                label="SMS"
                onChange={() => setState(prev => ({...prev, value2: !state.value2}))}
            />
            <ToggleSwitch
                className="m-r-4"
                checked={state.value3 || state.value1}
                disabled={state.value1}
                label="Email"
                onChange={() => setState(prev => ({...prev, value3: !state.value3}))}
            />
        </div>
    )}
</State>

<State initial={{value1: true, value2: true, value3: true}}>
    {([state, setState]) => (
        <div>
            <BodyText className="m-b-2">Notification settings:</BodyText>
            <ToggleSwitch
                className="m-r-4"
                checked={state.value1}
                label="Enable all notifications"
                onChange={() => setState(prev => ({...prev, value1: !state.value1}))}
            />
            <ToggleSwitch
                className="m-r-4"
                checked={state.value2 || state.value1}
                disabled={state.value1}
                label="SMS"
                onChange={() => setState(prev => ({...prev, value2: !state.value2}))}
            />
            <ToggleSwitch
                className="m-r-4"
                checked={state.value3 || state.value1}
                disabled={state.value1}
                label="Email"
                onChange={() => setState(prev => ({...prev, value3: !state.value3}))}
            />
        </div>
    )}
</State>

Best Practices

Toggle Switches in general should provide immediate results.
Toggle Switch options should be reducible to an On/Off choice.
Labels should be framed positively.
If using a Tooltip, display the current Toggle Switch state.
When in doubt, use the label to describe both the action and the subject of the Toggle Switch.
Use visual indicators such as disabled and active states on other elements to reenforce the state of the Toggle Switch.

Content Guidelines

Give a descriptive, direct label

The toggle switch label should describe what the control does when it is turned on. Rule of thumb: say the label name and add an “on/off”.

Use sentence case (capitalize only the first word and proper nouns) so control labels are easy to scan. Do not use periods for short phrases or single sentences.

Give the user the information they need to make an informed decision

The toggle switch label might not give the required information and context they need to make an informed decision about the option.

Inline help is the best option for this situation because it requires no user interaction and is always visible. Keep inline help to 1-2 sentences. Use the content guidelines for inline help.

Avoid using a tooltip to communicate this kind of information about an option. It’s an additional step for users to mouse over the tooltip to reveal its information, and users can’t refer to the tooltip content and take action at the same time.

<Form.ToggleSwitch
    label="Project labels"
    name="Toggle-1"
    value="Test1"
    description="This allows techs to view, apply and edit project labels given to job records"
    labelProps={{ help: "A project label can be attached to expense items like timesheet activities to provide a visual representation of expense spending." }}
/>

<Form.ToggleSwitch
    label="Project labels"
    name="Toggle-1"
    value="Test1"
    description="This allows techs to view, apply and edit project labels given to job records"
    labelProps={{ help: "A project label can be attached to expense items like timesheet activities to provide a visual representation of expense spending." }}
/>

Components

When needing a Yes/No choice, or needing to submit a form, use a Checkbox.
For more complex, mutually exclusive choices, use a Button Toggle or Radio.

Patterns

Form design pattern for how related controls are ordered.

Importing

import { ToggleSwitch } from '@servicetitan/design-system';