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 .

You can pass size="sm" to a MenuToggle to style it as a small toggle, such as within a breadcrumb.

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. You can also pass in variant="plainText" for a badge only toggle.

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 splitButtonItems property. Elements to be displayed before the toggle button must be included in the splitButtonItems.

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.

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

To link a split toggle label to the toggle's checkbox, pass both the label and the <MenuToggleCheckbox> component to splitButtonItems.

To link a split toggle label to the toggle button itself, pass the label to the <MenuToggle> component, instead of splitButtonItems.

To add an action to a split button, add a <MenuToggleAction> to the splitButtonItems property.

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.

To indicate the toggle contains placeholder text, pass the isPlaceholder property to the MenuToggle.