Button
- Usage
- Styling
- Styles
- Buttons with Icons
- Buttons with Images
- Disabled
- Focus
- Keyboard Usage
- Best Practices
- Related Components
The Button component allows users to perform actions. It comes in several different style variants and supports icons as well as text labels.
new tab
<vaadin-horizontal-layout theme="spacing" style="align-items: baseline">
<vaadin-button @click="${() => this.counter++}">Button</vaadin-button>
<p>Clicked ${this.counter} times</p>
</vaadin-horizontal-layout>Styles
The following variants can be used to distinguish between actions of different importance in the UI:
new tab
<vaadin-button theme="primary">Primary</vaadin-button>
<vaadin-button theme="secondary">Secondary</vaadin-button>
<vaadin-button theme="tertiary">Tertiary</vaadin-button>| Variant | Usage Recommendation |
|---|---|
Primary | This is the most important action in a view or in part of one. It’s the main closure or continuation action (e.g., Save) in a form or dialog. Avoid presenting the user with more than one at any time. |
Secondary | This is the default style recommended for most actions. It can be the alternate or negative closure actions (e.g., Cancel) in a form or dialog. |
Tertiary | These are lower-importance actions — especially in parts of the UI with less space, such as cards, or repeated actions for items in lists, tables, etc. Caution: this can be mistaken for non-interactive text. |
Danger & Error Variants
This is a style for distinguishing actions related to dangers, warnings, or errors. Dangerous actions would be those that lose or destroy data.
new tab
<vaadin-button theme="primary error">Primary</vaadin-button>
<vaadin-button theme="secondary error">Secondary</vaadin-button>
<vaadin-button theme="tertiary error">Tertiary</vaadin-button>Primary danger buttons should only be used when a dangerous action is the most likely action. An example of this would be the affirmative Delete action in a deletion confirmation dialog. Secondary and Tertiary variants can be used for actions related to current errors, such as resolving them or viewing their details.
Warning Variant
This is a style for distinguishing actions related to warnings: for example, in dialogs that are intended to warn the user, or to provide information that requires extra attention.
new tab
<vaadin-button theme="primary warning">Primary</vaadin-button>
<vaadin-button theme="secondary warning">Secondary</vaadin-button>
<vaadin-button theme="tertiary warning">Tertiary</vaadin-button>Size Variants
The following size variants are available for Button instances whose size needs to be different from the default:
new tab
<vaadin-button theme="large">Large</vaadin-button>
<vaadin-button theme="normal">Normal</vaadin-button>
<vaadin-button theme="small">Small</vaadin-button>| Variant | Usage Recommendation |
|---|---|
Large | For important call-to-action buttons — where more emphasis is needed. |
Normal | Default size. |
Small | Compact option for cramped parts of the UI — where a Tertiary variant isn’t deemed appropriate. |
|
Tip
|
Customize Default Button Size
Size variants should only be used in special cases. See Size and Space for details on how to change the default button size.
|
Miscellaneous Style Variants
The Tertiary Inline variant omits all white space around the label. This can be useful for embedding a Button as part of text content or another component. It shouldn’t be confused with a link.
The Success and Contrast variants should provide additional color options for buttons.
new tab
<vaadin-button theme="primary success">Primary</vaadin-button>
<vaadin-button theme="secondary success">Secondary</vaadin-button>
<vaadin-button theme="tertiary success">Tertiary</vaadin-button>new tab
<vaadin-button theme="primary contrast">Primary</vaadin-button>
<vaadin-button theme="secondary contrast">Secondary</vaadin-button>
<vaadin-button theme="tertiary contrast">Tertiary (avoid)</vaadin-button>The Tertiary + Contrast combination should be avoided because of similarity to non-interactive text elements.
|
Tip
|
Customize Default Button Colors
The standard Button colors can be adjusted using the Lumo color properties. Therefore, these variants shouldn’t be used to replace standard buttons only to achieve a different color.
|
Buttons with Icons
Buttons can have icons instead of text, or they can have icons along with text.
new tab
<!-- Icon button using an aria-label to provide a textual alternative
to screen readers -->
<vaadin-button theme="icon" aria-label="Add item">
<vaadin-icon icon="vaadin:plus"></vaadin-icon>
</vaadin-button>
<!-- Icon button using a tooltip to provide a textual description of
the action that it triggers -->
<vaadin-button theme="icon" aria-label="Close">
<vaadin-icon icon="vaadin:close-small"></vaadin-icon>
<vaadin-tooltip slot="tooltip" text="Close the dialog"></vaadin-tooltip>
</vaadin-button>
<vaadin-button>
<vaadin-icon icon="vaadin:arrow-left" slot="prefix"></vaadin-icon>
Left
</vaadin-button>
<vaadin-button>
Right
<vaadin-icon icon="vaadin:arrow-right" slot="suffix"></vaadin-icon>
</vaadin-button>Use icons sparingly. Most actions are difficult to represent reliably with icons. The benefit of icons plus text should be weighed against the visual clutter they create.
Icon-only buttons should be used primarily for common recurring actions with highly standardized, universally understood icons (e.g., a cross for close), and for actions that are repeated, such as in lists and tables. They should also include a textual alternative for screen readers using the aria-label attribute (see the first two buttons in the previous example).
Additionally, tooltips can be added to provide a description of the action that the button triggers (see the Close button in the previous example).
|
Note
|
Icon-Only Button Style Variant
Use the icon / LUMO_ICON theme variant on icon-only buttons to reduce the white space on either side of the icon. The Flow Button component automatically applies the icon variant if the icon is the only child of the component.
|
Buttons with Images
Images on buttons can be used like icons. See the icon usage recommendations for more information.
new tab
<vaadin-button theme="icon">
<img src="${img}" width="100" alt="Vaadin logo" />
</vaadin-button>Disabled
Buttons representing actions that aren’t currently available to the user should be either hidden or disabled. A disabled button is rendered as "dimmed", and is excluded from the focus order. This may be useful when you don’t want interactive UI elements to receive the focus using the tab key.
new tab
<vaadin-button theme="primary" disabled>Primary</vaadin-button>
<vaadin-button theme="secondary" disabled>Secondary</vaadin-button>
<vaadin-button theme="tertiary" disabled>Tertiary</vaadin-button>Hidden vs. Disabled
Hiding entirely an unavailable action is often preferable to a disabled button, as this reduces UI clutter. However, in certain situations, this can be problematic. If the user expects a button to be present — such as at the end of a form — hiding the button can cause confusion, even if the form clearly shows the presence of one or more invalid fields. Also, since a hidden button doesn’t occupy any space in the UI, toggling its visibility can cause unwanted changes in the layout of other elements.
Show Error on Click
As an alternative to hiding or disabling buttons, configure instead unavailable actions to show an error message when the button is clicked by using a Notification or an adjacent inline text element. This approach is the most accessible option, but may be frustrating to users who expect unavailable actions to be distinguished somehow from available actions.
Prevent Multiple Clicks
Buttons can be configured to be disabled when clicked. This can be useful especially for actions that take a bit longer to perform. Not only does this avoid the need for special handling of additional clicks while the action is in progress, but it also communicates to the user that the action was received successfully and is being processed.
new tab
<vaadin-horizontal-layout theme="spacing" style="align-items: center;">
<vaadin-button
?disabled=${this.isDisabled}
@click=${() => {
this.isDisabled = true;
this.fakeProgressBar.simulateProgress();
}}
style="flex: none;"
>Perform Action</vaadin-button
>
<fake-progress-bar
@progress-end=${() => {
this.isDisabled = false;
}}
></fake-progress-bar>
</vaadin-horizontal-layout>Focus
As with other components, the focus ring is only rendered when the button is focused by keyboard or programmatically.
Best Practices
Below are some best practice recommendations related to buttons and their labels.
Button Labels
A label should describe the action, preferably using active verbs, such as "View Details" rather than "Details". To avoid ambiguity, also specify the object of the verb, such as "Save Changes" instead of "Save". They also should be brief, ideally less than three words or twenty-five characters.
Button groups representing options, such as the buttons of a Confirm Dialog, should state what each option represents (e.g., "Save Changes"). Don’t label a button "Yes" since that requires the user to read the question being asked. It’ll increase the risk of selecting the wrong option.
Use ellipsis (i.e., …) when an action is not immediate, but requires more steps to complete. This is useful, for example, for destructive actions like "Delete…" when a Confirm Dialog is used to confirm the action before it’s executed.
ARIA Labels
The aria-label attribute can be used to provide a separate label for accessibility technologies (AT), such as screen readers. This is important, for example, for icon-only buttons that lack a visible label.
A button with a regular, visible label can also benefit from a separate aria-label to provide more context that may otherwise be difficult for an AT user to perceive. In the example here, each button’s aria-label specifies which email address is removed:
new tab
<vaadin-vertical-layout>
<vaadin-horizontal-layout theme="spacing">
<vaadin-email-field
id="primary-email"
label="Primary email address"
.value="${this.primaryEmail}"
@value-changed="${(event: EmailFieldValueChangedEvent) => {
this.primaryEmail = event.detail.value;
}}"
></vaadin-email-field>
<vaadin-button
arial-label="Remove primary email address"
@click="${() => {
this.primaryEmail = '';
}}"
>
Remove
</vaadin-button>
</vaadin-horizontal-layout>
<vaadin-horizontal-layout theme="spacing">
<vaadin-email-field
id="secondary-email"
label="Secondary email address"
.value="${this.secondaryEmail}"
@value-changed="${(event: EmailFieldValueChangedEvent) => {
this.secondaryEmail = event.detail.value;
}}"
></vaadin-email-field>
<vaadin-button
arial-label="Remove secondary email address"
@click="${() => {
this.secondaryEmail = '';
}}"
>
Remove
</vaadin-button>
</vaadin-horizontal-layout>
</vaadin-vertical-layout>Buttons in Forms
Buttons in forms should be placed below the form with which they’re associated. They should be aligned left, with the primary action first, followed by other actions, in order of importance.
new tab
<vaadin-vertical-layout theme="spacing">
<vaadin-form-layout .responsiveSteps="${[{ columns: 2 }]}">
<vaadin-text-field label="First name" value="John"></vaadin-text-field>
<vaadin-text-field label="Last name" value="Smith"></vaadin-text-field>
<vaadin-email-field
label="Email address"
value="john.smith@example.com"
colspan="2"
></vaadin-email-field>
</vaadin-form-layout>
<vaadin-horizontal-layout theme="spacing">
<vaadin-button theme="primary">Create account</vaadin-button>
<vaadin-button theme="secondary">Cancel</vaadin-button>
</vaadin-horizontal-layout>
</vaadin-vertical-layout>Buttons in Dialogs
Buttons in dialogs should be placed at the bottom of the dialog and aligned right. Primary action should be last, preceded by other actions. Dangerous actions should be aligned left, to avoid accidental clicks, especially if no confirmation step is included.
new tab
<vaadin-vertical-layout theme="spacing" style="align-items: stretch;">
<vaadin-form-layout .responsiveSteps="${[{ columns: 2 }]}">
<vaadin-text-field label="First name" value="John"></vaadin-text-field>
<vaadin-text-field label="Last name" value="Smith"></vaadin-text-field>
<vaadin-email-field
label="Email address"
value="john.smith@example.com"
colspan="2"
></vaadin-email-field>
</vaadin-form-layout>
<vaadin-horizontal-layout
theme="spacing"
style="flex-wrap: wrap; justify-content: flex-end;"
>
<vaadin-button theme="secondary error" style="margin-inline-end: auto;">
Delete
</vaadin-button>
<vaadin-button theme="secondary">Cancel</vaadin-button>
<vaadin-button theme="primary">Create account</vaadin-button>
</vaadin-horizontal-layout>
</vaadin-vertical-layout>Global vs. Selection-Specific Actions
In lists of selectable items — such as in a Grid — that provide actions applicable to the selected item, buttons for selection-specific actions should be placed apart from global actions that aren’t selection-specific. They should be located below the list of selectable items.
In the example below, the global Add User action is separated from the selection-specific actions below the Grid:
new tab
<vaadin-vertical-layout theme="spacing" style="align-items: stretch;">
<vaadin-horizontal-layout style="align-items: center;">
<h2 style="margin: 0 auto 0 0;">Users</h2>
<vaadin-button>Add user</vaadin-button>
</vaadin-horizontal-layout>
<vaadin-grid
.items="${this.items}"
@selected-items-changed="${(event: GridSelectedItemsChangedEvent<Person>) => {
this.selectedItems = event.target ? [...event.detail.value] : this.selectedItems;
}}"
>
<vaadin-grid-selection-column
auto-select
@select-all-changed="${(event: GridSelectionColumnSelectAllChangedEvent) => {
this.selectedItems = event.detail.value ? this.items : this.selectedItems;
}}"
></vaadin-grid-selection-column>
<vaadin-grid-column path="firstName"></vaadin-grid-column>
<vaadin-grid-column path="lastName"></vaadin-grid-column>
<vaadin-grid-column path="email"></vaadin-grid-column>
</vaadin-grid>
<vaadin-horizontal-layout theme="spacing" style="flex-wrap: wrap;">
<vaadin-button ?disabled="${this.selectedItems.length !== 1}">Edit profile</vaadin-button>
<vaadin-button ?disabled="${this.selectedItems.length !== 1}">
Manage permissions
</vaadin-button>
<vaadin-button ?disabled="${this.selectedItems.length !== 1}">
Reset password
</vaadin-button>
<vaadin-button
theme="error"
?disabled="${this.selectedItems.length === 0}"
style="margin-inline-start: auto;"
>
Delete
</vaadin-button>
</vaadin-horizontal-layout>
</vaadin-vertical-layout>