SplitButton

import { SplitButton } from '@uhg-abyss/web/ui/SplitButton';

Overview

The SplitButton component is a button that has a main action and a dropdown menu. It is used to display a set of actions or functions that can be triggered by the user. The component is designed to be flexible and customizable, allowing you to define the menu items, their actions, and how they are displayed.

The dropdown, known as the Action Menu, can contain single menu items, checkboxes, radio groups, and submenus. Each item can have an icon.

Label

Use the label prop to set the text of the main action button.

Outline

Use the outline prop to control the outline of the SplitButton. The default is true. When setting the prop to false, the border radius will be removed and the component will have a flat appearance.

Note: An outline should be used if the SplitButton is used on a background that does not meet the 3:1 color contrast ratio.

isDisabled

Use the isDisabled prop to disable the entire SplitButton

isLoading

Use the isLoading prop to place the Action Menu in a loading state. This will display a loading spinner in place of the menu items while the menu is loading.

You can also provide the optional prop loadingLabel for additional context when the menu is in a loading state. This prop takes the form of an object as explained in our LoadingSpinner documentation.

Use the menuItems prop to specify what will be displayed in the Action Menu. The prop requires an array of objects that have the following forms:

Action item

interface ActionMenuItemProps {
  title: string;
  onClick: Function;
  icon: ReactNode; //optional
  isSeparated: boolean; //optional
  disabled: boolean; //optional
}

Checkbox

interface ActionMenuCheckboxItemProps {
  checkboxes: Array<{
    label: string;
    checked: bool;
    onChange: func;
    disabled: bool; //optional
  }>;
}

Radio group

interface ActionMenuRadioItemProps {
  label: string;
  value: string;
  onChange: Function;
  radios: Array<{
    label: string;
    value: string;
    disabled: bool; //optional
  }>;
}

Submenu

interface ActionMenuItemGroupSubMenuItem {
  title: string;
  subMenu: ActionMenuItemGroupItem[]; // any of the above types
}

Inserting icons

There are two types of icons that can be added to the SplitButton:

Use the before prop to insert an icon before the main action button label.
Use the icon prop in the menu items to insert icons before to the item title. While this prop accepts any React node, the examples on this page use our IconSymbol component.

onClick

There are two types of onClick functions you can use with the SplitButton:

To provide an action to perform when clicking the main action button, use the onClick prop of the SplitButton component.
To provide an action to perform when clicking a menu item, use the onClick prop of the menu item object.

onChange

Use the onChange function to trigger a custom function when a checkbox or a radio item is clicked. You can use this to update your checked state, among other things.

When the disabled flag is set to true on a menu item, that item cannot be interacted with. This prop applies to all item types, including action items, checkboxes, and radio groups. The item will be visually styled to indicate that it is disabled.

isSeparated

When the isSeparated flag is set to true on a menu item, a horizontal divider will be inserted after that item. Checkbox and radio group items automatically render a divider both before and after the item, so no isSeparated flag is required. A divider will not be rendered before the first item or after the last item.

onOutsideClick

Use onOutsideClick prop to trigger a custom function when the user clicks outside an open menu.

Use the open and onOpenChange props together to control the dropdown open state. open is a boolean that determines whether the dropdown is open or closed, and onOpenChange is a function that is called when the open state changes. This allows you to manage the open state of the dropdown programmatically.

Height

Use the height prop to set a custom height for the Action Menu. The default height is 500px. This prop accepts any valid CSS height value.

SplitButton vs. DropdownMenu

DropdownMenu is a versatile component that can be used for various menu actions, while SplitButton is specifically designed for a button with a dropdown menu that allows users to perform an action or select from a list of options. SplitButton is more suitable when you want to combine a primary action with a secondary dropdown menu.