# Split button

- Entry point: `@koobiq/components/split-button`
- NgModule: `KbqSplitButtonModule`
- API: https://koobiq.io/api/split-button.md
- Page: https://koobiq.io/en/components/split-button/overview

A split button combines several related actions into a single control. The primary action is immediately accessible, while additional options are hidden in a dropdown menu.

[**Example: split-button** (`split-button-overview`)](https://koobiq.io/examples/split-button-overview.md)

## Style

A split button follows the same visual variants as a regular [button](https://koobiq.io/en/components/button.md).

[**Example: split-button-styles** (`split-button-styles`)](https://koobiq.io/examples/split-button-styles.md)

## Content

The primary action can be labeled with a caption and illustrated with an icon. In the variant without a caption, the menu button becomes narrower.

[**Example: split-button-content** (`split-button-content`)](https://koobiq.io/examples/split-button-content.md)

Long text in the primary button does not wrap to a new line — it is truncated with an ellipsis. Avoid buttons with long text.

[**Example: split-button-text-overflow** (`split-button-text-overflow`)](https://koobiq.io/examples/split-button-text-overflow.md)

## Disabled state

Either the primary or secondary action can be disabled individually, or the entire group can be disabled at once.

[**Example: split-button-disabled-state** (`split-button-disabled-state`)](https://koobiq.io/examples/split-button-disabled-state.md)

## In progress

The Progress state can be combined with any other state (Normal, Disabled, Active). Like the Disabled state, it can be applied to the entire button group or to an individual element.

[**Example: split-button-progress-state** (`split-button-progress-state`)](https://koobiq.io/examples/split-button-progress-state.md)

## Menu width matching the button

Menu positioning is configured the same way as in the [Dropdown](https://koobiq.io/en/components/dropdown.md) component. When the menu width is approximately equal to the split button's size, it is better to align them for visual consistency.

[**Example: split-button-menu-width** (`split-button-menu-width`)](https://koobiq.io/examples/split-button-menu-width.md)

## Accessibility

- **Grouping.** The host is announced as a `role="group"`: it ties the two actions together while each button stays a separate tab stop. When a page holds several split buttons, name the group — `<kbq-split-button aria-label="Save document">`.
- **Menu trigger.** The trigger is an icon-only button, so it carries no text and no accessible name of its own. Set one explicitly: `<button kbq-button aria-label="More options" [kbqDropdownTriggerFor]="menu">`.
- **Open state.** The trigger carries `aria-expanded`, so assistive technology announces whether the menu is currently open.
- **Keyboard.** `Tab` reaches the primary button and then the trigger, `Enter` and `Space` activate the focused one. On the trigger `ArrowDown` also opens the menu, and `Escape` closes it and returns focus to the trigger — the same model as in [Dropdown](https://koobiq.io/en/components/dropdown.md).
- **Disabled state.** A disabled button leaves the tab order and is announced as disabled: through the native `disabled` attribute on a `<button>` host, and through `aria-disabled` on hosts without native support, such as `<a>`.

## Recommendations

A split button is often confused with the more common [button menu](https://koobiq.io/en/components/dropdown.md), which consists of a single element that opens a dropdown list of commands. Use a split button only in exceptional cases:

- **When there is a clear and frequently used primary action.** A split button is ideal when in 80% of cases the user needs one action (for example, "Save"), but occasionally needs to choose a different option.
- **The menu actions are homogeneous and closely related to the primary action.** All items in the dropdown list must be variations or refinements of the primary action.
