Menu toggle

A toggle is collapsed until it is selected by a user.

When a user selects a toggle, it becomes expanded and is styled with a blue underline. To flag expanded toggles, and apply expanded styling, use the isExpanded property .

To disable the selection and expansion of a toggle, use the isDisabled property.

To display a count of selected items in a toggle, use the badge property.

To add a recognizable icon to a menu toggle, use the icon property. The following example adds a CogIcon to the toggle.

For most basic icons, it is recommended to wrap it inside our icon component.

You can also pass images into the icon property. The following example passes in an <Avatar> component with an imgAvatar.

This can be used alongside a text label that provides more context for the image.

Variant styling can be applied to menu toggles. In the following example, the toggle uses primary styling by passing variant="primary" into the <MenuToggle> component. Additional variant options include “default”, “plain”, “plainText”, “secondary”, and “typeahead”.

To apply plain styling to a menu toggle with an icon, pass in variant="plain". This will remove the default bottom border and caret. You may pass in an icon to serve as the menu toggle. The following example passes in an EllipsisVIcon.

If the toggle does not have any visible text content, use the aria-label property to provide an accessible name.

To apply plain styling to a menu toggle with a text label, pass in variant="plainText". Unlike the “plain” variant, “plainText” adds a caret pointing down in the toggle.

To add a checkbox (or other action/control) to a menu toggle, use a split button.

A <MenuToggle> can be rendered as a split button by adding a splitButtonOptions object. Elements to be displayed before the toggle button must be included in the items property of splitButtonOptions.

The following example shows a split button with a <MenuToggleCheckbox>.

Variant styling can be applied to split button toggles to adjust their appearance for different scenarios. Both "primary" and "secondary" variants can be used with split button toggles.

To add a text label to a split button toggle, pass children to the <MenuToggle> component.

You can allow users to select a toggle checkbox by clicking either the checkbox or the text label.

To do so, pass children to the <MenuToggleCheckbox> component. When the menu toggle text is clicked, the checkbox's onChange callback will be triggered.

To add an action to a split button, pass variant='action' into splitButtonOptions and add a <MenuToggleAction> to the items property of splitButtonOptions.

Actions may be used with primary and secondary toggle variants.

A full height toggle fills the height of its parent. To flag a full height toggle, use the isFullHeight property.

In the following example, the toggle fills the size of the "80px" <div> element that it is within.

A full width toggle fills the width of its parent. To flag a full width toggle, use the isFullWidth property.

In the following example, the toggle fills the width of its parent as the window size changes.

To create a typeahead toggle, pass in variant="typeahead" to the <MenuToggle>. Then, pass a <TextInputGroup> component as a child of the <MenuToggle>.

To create a multiple typeahead toggle, pass a <TextInputGroup> component implemented like the text input group's filter example as a child of <MenuToggle>.

To create a toggle with a status, pass in the status property to the MenuToggle. The default icon associated with each status may be overridden by using the statusIcon property.

When the status value is "warning" or "danger", you must include helper text that conveys what is causing the warning/error.