sp-split-button
Attributes and Properties #
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
autofocus | autofocus | boolean | false | When this control is rendered, focus it automatically |
dir | dir | 'ltr' | 'rtl' | 'ltr' | |
disabled | disabled | boolean | false | Disable this control. It will not receive focus or events |
focused | focused | boolean | false | |
icons | icons | 'only' | 'none' | undefined | | |
invalid | invalid | boolean | false | |
label | label | string | undefined | | |
left | left | boolean | false | |
open | open | boolean | false | |
placement | placement | "auto" | "auto-start" | "auto-end" | "top" | "bottom" | "right" | "left" | "top-start" | "top-end" | "bottom-start" | "bottom-end" | "right-start" | "right-end" | "left-start" | "left-end" | "none" | 'bottom-start' | |
quiet | quiet | boolean | false | |
readonly | readonly | boolean | false | |
size | size | ElementSize | | |
tabIndex | tabIndex | number | | The tab index to apply to this control. See general documentation about the tabindex HTML property |
type | type | 'field' | 'more' | 'field' | |
value | value | string | '' | |
variant | variant | ButtonVariants | 'cta' | The visual variant to apply to this button. |
Slots #
| Name | Description |
|---|---|
default slot | menu items to be listed in the Button |
Events #
| Name | Type | Description |
|---|---|---|
change | Event | Announces that the `value` of the element has changed |
sp-closed | Event | Announces that the overlay has been closed |
sp-opened | Event | Announces that the overlay has been opened |
CSS Custom Properties #
| Name | Default |
|---|---|
--spectrum-alias-border-radius-small | var(--spectrum-global-dimension-size-25) |
--spectrum-button-m-primary-texticon-border-radius | var(--spectrum-global-dimension-size-200) |
--spectrum-button-m-primary-texticon-border-size | var(--spectrum-alias-border-size-thick) |
--spectrum-button-m-primary-texticon-padding-left | undefined |
--spectrum-button-m-primary-texticon-padding-right | var(--spectrum-global-dimension-size-200) |
Description #
An sp-split-button surfaces an immediately envokable action via it's main button, as well as a list of alternative actions in its toggleable menu overlay. By default, any actions envoked from the overlay will replace the main action button. When leveraging [type="more"] the action will be envoked, but the main button will remain the action initally persribed by the implementor.
Usage #
yarn add @spectrum-web-components/split-button
Import the side effectful registration of <sp-split-button> via:
import '@spectrum-web-components/split-button/sp-split-button.js';
The default of <sp-split-button> will load dependencies in @spectrum-web-components/overlay asynchronously via a dynamic import. In the case that you would like to import those tranverse dependencies statically, import the side effectful registration of <sp-split-button> as follows:
import '@spectrum-web-components/split-button/sync/sp-split-button.js';
When looking to leverage the SplitButton base class as a type and/or for extension purposes, do so via:
import { SplitButton } from '@spectrum-web-components/split-button';
Sizes #
<sp-split-button size="s">
Split Button
<sp-menu-item>Option 1</sp-menu-item>
<sp-menu-item>Option Extended</sp-menu-item>
</sp-split-button>
<sp-split-button size="m">
Split Button
<sp-menu-item>Option 1</sp-menu-item>
<sp-menu-item>Option Extended</sp-menu-item>
</sp-split-button>
<sp-split-button size="l">
<sp-menu-item>Option 1</sp-menu-item>
<sp-menu-item>Option Extended</sp-menu-item>
</sp-split-button>
<sp-split-button size="xl">
<sp-menu-item>Option 1</sp-menu-item>
<sp-menu-item>Option Extended</sp-menu-item>
</sp-split-button>
Variants #
CTA #
<sp-split-button>
<sp-menu-item>Option 1</sp-menu-item>
<sp-menu-item>Option Extended</sp-menu-item>
</sp-split-button>
<sp-split-button left>
<sp-menu-item>Option 1</sp-menu-item>
<sp-menu-item>Option Extended</sp-menu-item>
</sp-split-button>
Primary #
<sp-split-button variant="primary">
<sp-menu-item>Option 1</sp-menu-item>
<sp-menu-item>Option Extended</sp-menu-item>
</sp-split-button>
<sp-split-button left variant="primary">
<sp-menu-item>Option 1</sp-menu-item>
<sp-menu-item>Option Extended</sp-menu-item>
</sp-split-button>
Secondary #
<sp-split-button variant="secondary">
<sp-menu-item>Option 1</sp-menu-item>
<sp-menu-item>Option Extended</sp-menu-item>
</sp-split-button>
<sp-split-button left>
<sp-menu-item>Option 1</sp-menu-item>
<sp-menu-item>Option Extended</sp-menu-item>
</sp-split-button>
More button #
When using the more value of the type attribute, an <sp-split-button> will maintain its default option value without regard to the most recently used option.
CTA #
<sp-split-button type="more">
<sp-menu-item>Option 1</sp-menu-item>
<sp-menu-item>Option Extended</sp-menu-item>
</sp-split-button>
<sp-split-button type="more" left>
<sp-menu-item>Option 1</sp-menu-item>
<sp-menu-item>Option Extended</sp-menu-item>
</sp-split-button>
Primary #
<sp-split-button type="more" variant="primary">
<sp-menu-item>Option 1</sp-menu-item>
<sp-menu-item>Option Extended</sp-menu-item>
</sp-split-button>
<sp-split-button type="more" left variant="primary">
<sp-menu-item>Option 1</sp-menu-item>
<sp-menu-item>Option Extended</sp-menu-item>
</sp-split-button>
Secondary #
<sp-split-button type="more" variant="secondary">
<sp-menu-item>Option 1</sp-menu-item>
<sp-menu-item>Option Extended</sp-menu-item>
</sp-split-button>
<sp-split-button type="more" left variant="secondary">
<sp-menu-item>Option 1</sp-menu-item>
<sp-menu-item>Option Extended</sp-menu-item>
</sp-split-button>