ToggleButton

This component groups related options and behaves similarly to a radio button.

Basic Usage


import {
    ToggleButton,
    ToggleButtonOptionGroup,
    ToggleButtonOption
} from '@krakentech/coral';
 
const options = [
    { label: 'Half-hourly', value: 'half-hourly' },
    { label: 'Monthly', value: 'monthly' },
    { label: 'Daily', value: 'daily' },
];
 
<ToggleButton>
    <ToggleButtonOptionGroup>
        <Stack gap="xxs">
            {options.map(({ value, label }) => (
                <ToggleButtonOption value={value} key={value.toString()}>
                    {label}
                </ToggleButtonOption>
            ))}
        </Stack>
    </ToggleButtonOptionGroup>
</ToggleButton>;

Properties

value


const [value, setValue] = useState(
    options[2].value
);
 
<ToggleButton value={value}>
    <ToggleButtonOptionGroup>
        <Stack gap="xxs">
            {options.map(({ value, label }) => (
                <ToggleButtonOption
                    value={value}
                    key={value.toString()}
                >
                    {label}
                </ToggleButtonOption>
            ))}
        </Stack>
    </ToggleButtonOptionGroup>
</ToggleButton>
 
<Button
    size="small"
    onClick={() => setValue(options[0].value)}
>
    Change value
</Button>

defaultValue


<ToggleButton defaultValue={'half-hourly'}>
    <ToggleButtonOptionGroup>
        <Stack gap="xxs">
            {options.map(({ value, label }) => (
                <ToggleButtonOption value={value} key={value.toString()}>
                    {label}
                </ToggleButtonOption>
            ))}
        </Stack>
    </ToggleButtonOptionGroup>
</ToggleButton>

disabled


<ToggleButton disabled>
    <ToggleButtonOptionGroup>
        <Stack gap="xxs">
            {options.map(({ value, label }) => (
                <ToggleButtonOption value={value} key={value.toString()}>
                    {label}
                </ToggleButtonOption>
            ))}
        </Stack>
    </ToggleButtonOptionGroup>
</ToggleButton>

error / errorMessage


<ToggleButton error errorMessage="Please select a value">
    <ToggleButtonOptionGroup>
        <Stack gap="xxs">
            {options.map(({ value, label }) => (
                <ToggleButtonOption value={value} key={value.toString()}>
                    {label}
                </ToggleButtonOption>
            ))}
        </Stack>
    </ToggleButtonOptionGroup>
</ToggleButton>

Please select a value

fullWidth


<ToggleButton fullWidth>
    <ToggleButtonOptionGroup>
        <Stack gap="xxs">
            {options.map(({ value, label }) => (
                <ToggleButtonOption value={value} key={value.toString()}>
                    {label}
                </ToggleButtonOption>
            ))}
        </Stack>
    </ToggleButtonOptionGroup>
</ToggleButton>

label


const label = 'Custom label';
 
<ToggleButton>
    <ToggleButtonLabel label={label} />
 
    <ToggleButtonOptionGroup ariaLabelledby={label}>
        <Stack gap="xxs">
            {options.map(({ value, label }) => (
                <ToggleButtonOption value={value} key={value.toString()}>
                    {label}
                </ToggleButtonOption>
            ))}
        </Stack>
    </ToggleButtonOptionGroup>
</ToggleButton>;

Custom label

optional

Note: You must have a ToggleButtonLabel sub-component to use the optional prop.


<ToggleButton optional>
    <ToggleButtonLabel label={label} />
 
    <ToggleButtonOptionGroup ariaLabelledby={label}>
        <Stack gap="xxs">
            {options.map(({ value, label }) => (
                <ToggleButtonOption value={value} key={value.toString()}>
                    {label}
                </ToggleButtonOption>
            ))}
        </Stack>
    </ToggleButtonOptionGroup>
</ToggleButton>

Custom label (optional)

size


<ToggleButton size="small">
    <ToggleButtonOptionGroup>
        <Stack gap="xxs">
            {options.map(({ value, label }) => (
                <ToggleButtonOption value={value} key={value.toString()}>
                    {label}
                </ToggleButtonOption>
            ))}
        </Stack>
    </ToggleButtonOptionGroup>
</ToggleButton>

Event Handling


<ToggleButton
    onBlur={() => {}}
    onChange={(event, value) => {}}
    onFocus={() => {}}
>
    ...
</ToggleButton>

Responsiveness


<ToggleButton fullWidth={{ base: true, lg: false }}>
    <ToggleButtonOptionGroup>
        <Stack gap="xxs">
            {options.map(({ value, label }) => (
                <ToggleButtonOption value={value} key={value.toString()}>
                    {label}
                </ToggleButtonOption>
            ))}
        </Stack>
    </ToggleButtonOptionGroup>
</ToggleButton>

Full API

Name	Type	Default
`defaultValue`	`ToggleValue` If set, a default value will be set for the toggle button.
`disabled`	`boolean` If `true`, the component will be disabled and not respond to user interactions.	`false`
`error`	`boolean` If `true`, the component will have error styling set.
`errorMessage`	`string` If set, the `ErrorMessage` component will be rendered below the input with this text.	`'Please select an option'`
`fullWidth`	`ResponsiveVariant<boolean>` If `true`, the button will take up the full width of its container.	`false`
`onBlur`	`FocusEventHandler<HTMLButtonElement>` Callback fired when the toggle button loses user focus.
`onChange`	`(e: MouseEvent<HTMLButtonElement, MouseEvent>, value: ToggleValue) => void` Callback fired each time the user clicks a toggle button. `event` The event source of the callback. `value` The value of the toggle button that was clicked.
`onFocus`	`FocusEventHandler<HTMLButtonElement>` Callback fired each time the user focuses on a toggle button.
`optional`	`boolean` Add an optional flag to the label for this field (controlled by https://coral-oe.vercel.app/?path=/docs/guides-configuration—docs#overrides-optional-indicator optionalIndicator). This should be set to true if you have set this field to be optional in your validation schema.	`false`
`value`	`ToggleValue \| null` `value` should be supplied by the parent component to control the value of the ToggleButton input.
`size`	`"small" \| "medium"` The size of the ToggleButton, which affects its padding.	`medium`
`children`	`ReactNode`

Design

Good to know

Choose a toggle button when you want a user to select one option from various options. This is commonly used already to allow the user to select their house type or consumption usage from various options.

Can the user de-select an option?

No, to ‘de-select’ the current option you would need to select another option.

Can I include more than 4 options?

There isn’t a limit, however, we expect people to use common sense in that there shouldn’t be 10 options. A great rule of thumb is if you need more than 4 options then it should probably be an auto-complete. Doing so will be transferable for mobile also, unlike an endless toggle button.

Component breakdown

Corner radius: 12px
Border: 2px
Text: Heading 5 & 6
Hover fill: Blue Tang
Active fill: Ink
Item padding: 4px | Horizontal padding: 4px | Vertical padding: 4px