Components / Library version 3.26.0

Button

The button component styles the display of buttons while ensuring adherence to basic accessibility guidelines. There are seven visual types as listed below. Additionally, various properties will change the appearance and functionality of each button.

Button Types

Primary Buttons (primary)

Primary buttons have the traditional appearance of buttons with text and generally serve to guide the user to a preferred action. There should ideally only be one on the page or section.

Secondary Buttons (secondary)

Like primary buttons, secondary buttons have the traditional button appearance with text. They do not connote a preferred action, and are often used in conjunction with primary buttons.

Text Only (textonly)

Text only button elements, with or without an icon, do not have the typical appearance of buttons. They are generally used for less commonly used or less desirable actions in situations where the user is performing other actions, e.g. in managing a widget where the prefered action is to update various fields, a text only button may be used for the less commonly used action of deleting the entire widget.

Icon Only (icononly)

Icon only buttons have the typical appearance of buttons but rather than having text they only have an icon. They are generally only used in situations where the icon is considered to be easily recognizable. They do require associated text in order to meet accessibility guidelines.

Icon Only Buttons that Navigate After an Action (navigational)

Icon only buttons that serve the purpose of completing an action and then navigating to another page or dialog have a different appearance in Ripple. They are typically used for back buttons in flyout panels and similar situations.

Positive/Negative Buttons (pairpositive and pairnegative)

Used together, pair positive and pair negative buttons serve a binary purpose where one button is generally associated with a positive quality and the other negative, but neither is preferred, such as approve/reject.

Delete Buttons (property: permanentlydelete)

Although not a specific button type, it is worth mentioning that the button component has a property called permanently delete that styles the primary button in a manner that suggests danger. It is to be used sparingly and only in situations where the user is taking a dangerous action that cannot be undone.

Properties Examples Accessibility Notes

** Required in certain cases

icon **
string
The Material Design Icon character code (e.g. f1c0). Required if button-type is set to icononly.
tooltip **
string
Text to display in the tooltip for icononly and navigational buttons. Required for these two types.
button-type
primary | secondary | textonly | icononly | navigational | pairpositive | pairnegative

Style of the button. Defaults to secondary.

Properties for each style:

disabled: Optional customBackground: Optional permanently-delete: Optional disabled: Optional customBackground: Optional label-for-identical-buttons: SEE DETAILS BELOW icon: Optional permanently-delete: Optional text-wrap: Optional disabled: Optional customBackground: Optional label-for-identical-buttons: SEE DETAILS BELOW icon: Required tooltip: Required if icon is not a commonly used icon tooltip-position: Optional label-for-identical-buttons: SEE DETAILS BELOW icon-flip: Optional icon-rotate: Optional icon-size: Optional disabled: Optional customBackground: Optional icon: Required. tooltip: Required if icon is not a commonly used icon tooltip-position: Optional. label-for-identical-buttons: SEE DETAILS BELOW icon-flip: Optional icon-rotate: Optional icon-size: Optional. disabled: Optional. customBackground: Optional
disabled: Optional label-for-identical-buttons: See details below disabled: Optional label-for-identical-buttons: See details below
custom-background
dark
Use to render button styles for dark background.
disabled
boolean
Disables the button.
icon-flip
horizontal | vertical
For use with the icon property, flips the icon along the axis specified.
icon-rotate
number
For use with the icon property, rotates icon by the degrees specified.
icon-size
string
Change size of the icon. Should be a valid CSS value, like 22px or 1.3rem.
label-for-identical-buttons
string
Use only in this specific case:
If a page has several buttons with identical text or identical tooltips, the aria-label of the button needs to include more descriptive information than the text or tooltip displayed. In that case, set this prop to the more descriptive name, and leave the button text or the tooltip prop unchanged.
permanently-delete
boolean
Use to render a style for buttons that permanently delete. Defaults to false.
text-wrap
boolean
For text-only buttons. Defaults to true (the text will wrap over several lines if necessary). When set to false, the text will be truncated if it is too long to be displayed. In that case ellipsis will be shown and a tooltip will allow the user to see the full text.
tooltip-position
top | bottom | left | right | top-left | top-right | bottom-left | bottom-right
Sets the position of the tooltip. Defaults to bottom-right. If there is not enough space to display the tooltip at the indicated position, the component will automatically reposition it.

Deprecated properties

button-style
primary | secondary | textonly | icononly | navigational
Deprecated in favor of button-type. Previously, the style of the button.

Commonly used icons

Icon Code
f156
f3eb
f739
f12c
f1c0
f349
f207
f1d9
f04d
f054
f141
f142
f35e
f35d
f30d
f645
f4bb

See the full list of icons here Opens a new window .

Usage in HTML

Edit the code below to see changes reflected in the example above.

Usage in Elm

Code generated from HTML.

Javascript Sample

Example code for functionality.

Usage with React wrappers

Keyboard Support

Key Function
Enter Space Activates the button.

Button types pairnegative and pairpositive are part of a pair and must be used together.

In a compound component like Select or Action Menu, child components are rendered in the parent's slot element, part of its shadow DOM tree. Slots essentially serve as a placeholder for markup that you the developer define in the light DOM tree, like <wm-menuitem>, <wm-option>, text content, or other child elements.

The browser distributes the child elements defined in the light DOM into the shadow DOM of the parent. The result is a flattened DOM tree—a merger of the the light DOM and the shadow DOM. This flattened tree is what you see in DevTools and what is rendered on the page.

With the standard implementation of the component, dynamically updating the child items will throw an error. Elm's efficient diffing of the DOM will register that only the child items have changed and try to update them, but the component has already been composed.

Rendering the component in a Keyed node and giving it a dynamic id will cause the entire component, rather than just the child items, to render anew, avoiding the error.