Components / Library Version 4.9.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.

PropertiesExamplesAccessibilityNotes

** 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.
is-submit
boolean
Allows the button to submit a form.
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.

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.