Skip to main content

V1ToggleGroup

Combines checkboxes to give multiple options for selection.

github
View source code
figma
View design
V1 components are not compatible with the flattenTokens hook or the DefaultPropsProvider, nor can they be themed using component-level design tokens.
A future redesign will deliver V2 versions of these components and make them compatible with these features.
import { V1ToggleGroup } from '@uhg-abyss/web/ui/ToggleGroup';

Usage​

    () => {
      const [value, setValue] = useState<string[]>(['sun']);
    

      useEffect(() => {
        console.log('value', value);
      }, [value]);
    

      return (
        <V1ToggleGroup
          label="ToggleGroup Sandbox"
          subText="This is subtext"
          onChange={(val) => setValue(val)}
          value={value}
        >
          <V1ToggleGroup.Toggle label="Sun" value="sun" ariaLabel="Sunday" />
          <V1ToggleGroup.Toggle label="Mon" value="mon" ariaLabel="Monday" />
          <V1ToggleGroup.Toggle label="Tue" value="tue" ariaLabel="Tuesday" />
          <V1ToggleGroup.Toggle label="Wed" value="wed" ariaLabel="Wednesday" />
          <V1ToggleGroup.Toggle label="Thu" value="thu" ariaLabel="Thursday" />
          <V1ToggleGroup.Toggle label="Fri" value="fri" ariaLabel="Friday" />
          <V1ToggleGroup.Toggle label="Sat" value="sat" ariaLabel="Saturday" />
        </V1ToggleGroup>
      );
    };

    Using useForm and FormProvider simplifies form management by providing out-of-the-box validation, form state handling, and performance optimizations, leveraging the power of react-hook-form.

    useState​

    Using the useState hook gets values from the component state.

    Label​

    Use the label prop to display a label above the toggle group. To hide the label, set hideLabel to true.

    Use isRequired for further customization.

    useState only

    If using useForm, do not use isRequired. The same functionality can be achieved with required: true in validators.

    Subtext​

    Use the subText prop to display helpful information related to the toggle group field. The prop accepts either a string or an object of the form:

    {
      text: string;
      position: 'above' | 'below';
    }

    The position property determines where the subtext will be displayed in relation to the toggle group field. The default value is 'below'.

    Helper​

    Use the helper prop to display a help icon next to the label. Simply passing a string value will render the default helper, a Tooltip containing that string. The helper can be customized by passing in a node. It is recommended to use either a Tooltip or a Popover. See When should I use a Tooltip vs. a Popover? for more information on best practices regarding the two.

    Error message (useState)​

    Use the errorMessage prop to display a custom error message below the toggle group field when using useState.

    Success message​

    Form Compatibility
    useState
    useForm

    Use the successMessage prop to display a custom success message below the input field. To provide a single success message across all form input components using useForm/FormProvider, you can provide successMessage to FormProvider as shown here.

    Rounded​

    Use the rounded prop to change the style of the V1ToggleGroup from Rectangle to rounded. The default is squared and set to false.

    Border radius​

    Use the borderRadius prop to set to set the border radius of the container, as well as the selected toggle item. There are two preset values you can use, $md, and $lg, or you can input a custom value. The default value is $md.

    Disabled​

    Set the isDisabled prop to true to disable all toggle items in the group. Individual toggle items can be disabled by setting isDisabled to true in their respective V1ToggleGroup.Toggle instead of the outer component.

    Display​

    Use the display prop to set the direction in which the toggle group appears. The default is set to 'column'.

    V1ToggleGroup Props​

    Name
    Type
    		DefaultRequiredA11yDescription
    borderRadius
    string | number | undefined
    '$md'
    The border radius of the ToggleGroup.
    borderRadiuses
    { [key: string]: string | number; } | undefined
    { md: '4px', lg: '100px' }
    Custom border radii for different sizes of the ToggleGroup.
    children
    string | number | bigint | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...> | null | undefined
    The content of the ToggleGroup component.
    className
    string | undefined
    CSS class name to apply to each element within the component
    css
    CSSProperties | Partial<Record<"abyss-toggle-group-label" | "abyss-toggle-group-root" | "abyss-toggle-group-container" | "abyss-toggle-group-descriptors", CSSProperties>> | undefined
    Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation
    See CSS Prop Styling for more information
    data-testid
    string | undefined
    Suffix used to create a unique ID used for automated testing
    See Component Testing for more information
    disableDefaultProviderProps
    boolean | undefined
    false
    If set to true, the component will not use the DefaultPropsProvider values.

    If you aren’t using the DefaultPropsProvider, this prop can be ignored.
    display
    "row" | "column" | undefined
    'row'
    The display style of the ToggleGroup.
    errorMessage
    string | undefined
    Error message to display for the input. Only used when not in a FormProvider.
    errorMessage should not exist in useForm mode.
    helper
    string | number | bigint | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...> | null | undefined
    Helper element next to label
    hiddenFrom
    Breakpoint | undefined
    When defined, the component is hidden once the screen width reaches the specified breakpoint.
    hideLabel
    boolean | undefined
    false
    If true, hides the label visually while keeping it accessible to screen readers.
    highlighted
    boolean | undefined
    false
    If true, the input field will be highlighted
    isDisabled
    boolean | undefined
    false
    If true, the input will be disabled
    isRequired
    boolean | undefined
    Whether the input is required. Only used when not in a FormProvider.
    isRequired should not exist in useForm mode.
    label
    string
    The label for the input; associated with it so screen readers announce it as the input's accessible name.
    model
    string | undefined
    model should not exist in useState mode.
    Model name for form validation. Only used when in a FormProvider.
    onBlur
    FocusEventHandler<HTMLInputElement> | undefined
    Callback function executed when the input is blurred
    onChange
    ((value: string[]) => void) | undefined
    Event handler for the onChange event of the ToggleGroup.
    onFocus
    FocusEventHandler<HTMLInputElement> | undefined
    Callback function executed when the input is focused
    rounded
    boolean | undefined
    false
    Whether the ToggleGroup has rounded corners.
    slotProps
    Partial<Record<ToSlotKey<{ root: LeafSlotDef<"fieldset", undefined>; label: LeafSlotDef<"div", undefined>; container: LeafSlotDef<"div", undefined>; descriptors: LeafSlotDef<...>; }, "toggle-group">, SlotPropsLeafValue>> | undefined
    Slot props for overriding internal elements
    subText
    string | { text: string; position: SubTextPosition; } | undefined
    Additional descriptive text for the input
    successMessage
    string | undefined
    Success message to display for the input
    validators
    RegisterOptions | undefined
    validators should not exist in useState mode.
    Validators for the input. Only used when in a FormProvider.
    value
    ((string | number | readonly string[]) & string[]) | undefined
    The value of the input. Only used when not in a FormProvider.
    value should not exist in useForm mode.
    visibleFrom
    Breakpoint | undefined
    When defined, the component is hidden until the screen width reaches the specified breakpoint.

    V1ToggleGroup.Toggle Props​

    Name
    Type
    		DefaultRequiredA11yDescription
    ariaLabel
    string | undefined
    Adds an aria-label to the Toggle. Use when label is an icon or abbreviation.
    className
    string | undefined
    CSS class name to apply to each element within the component
    css
    CSSProperties | Partial<Record<"abyss-toggle-input-root" | "abyss-toggle-input-checkbox" | "abyss-toggle-input-label", CSSProperties>> | undefined
    Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation
    See CSS Prop Styling for more information
    data-testid
    string | undefined
    Suffix used to create a unique ID used for automated testing
    See Component Testing for more information
    disableDefaultProviderProps
    boolean | undefined
    false
    If set to true, the component will not use the DefaultPropsProvider values.

    If you aren’t using the DefaultPropsProvider, this prop can be ignored.
    hiddenFrom
    Breakpoint | undefined
    When defined, the component is hidden once the screen width reaches the specified breakpoint.
    isDisabled
    boolean | undefined
    false
    If true, the Toggle will be disabled
    label
    string | number | bigint | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...> | null | undefined
    The label for the Toggle
    onBlur
    FocusEventHandler<HTMLInputElement> | undefined
    onChange
    ChangeEventHandler<HTMLInputElement> | undefined
    onFocus
    FocusEventHandler<HTMLInputElement> | undefined
    slotProps
    Partial<Record<string, SlotPropsValue<string>>> | undefined
    Props to pass to individual internal slots of the component, keyed by the slot name
    (e.g. 'button-root'). Supports className, css, style, aria-*, data-*,
    data-testid, and nested slotProps for child Abyss components.
    See slotProps for more information
    value
    string
    The value of the Toggle
    visibleFrom
    Breakpoint | undefined
    When defined, the component is hidden until the screen width reaches the specified breakpoint.

    V1ToggleGroup Classes​

    Class NameDescription
    .abyss-toggle-group-containerToggleGroup container
    .abyss-toggle-group-descriptorsToggleGroup descriptors
    .abyss-toggle-group-labelToggleGroup label
    .abyss-toggle-group-rootToggleGroup root element

    V1ToggleGroup.Toggle Classes​

    Class NameDescription
    .abyss-toggle-input-checkboxToggle input type
    .abyss-toggle-input-labelToggle input label
    .abyss-toggle-input-rootToggle input root

    At its core, V1ToggleGroup functions like a checkbox group.

    A checkbox group is a set of checkable checkboxes, where more than one of the checkboxes can be checked at a time. Some implementations may initialize the set with all checkboxes in the unchecked state in order to force the user to check one or more of the checkboxes before moving past a certain point in the workflow.

    Use the ariaLabel prop in V1ToggleGroup.Toggle when using abbreviated words or icons. This will include an "aria-label" for screen readers.

    Keyboard Interactions​

    KeyDescription
    TabMoves focus to first element and then next items in the group Tab sequence
    SpaceWhen focus is on an unchecked checkbox item, checks it.
    Table of Contents