sp-split-button

Examples API

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 #

See it on NPM! How big is this package in your project? Try it on webcomponents.dev

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 #

Small
<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>
Medium
<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>
Large
<sp-split-button size="l">
<sp-menu-item>Option 1</sp-menu-item>
<sp-menu-item>Option Extended</sp-menu-item>
</sp-split-button>
Extra Large
<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>