Button

Usage

When to use

• To trigger an action or event, like a form submission.

When not to use

• When navigating to another destination, consider Inline or Standalone link.
• To display multiple actions under a single button, use Dropdown.

Sizes

Medium is the preferred size, but use a Button size that best fits the UI (e.g., don’t use a large button in a table).

Full-width buttons fill 100% of the parent container. Use full-width Buttons sparingly.

Full-width button

Types

Primary

Use Primary for the most important action on a page, e.g., for submitting a form. Avoid using multiple Primary buttons on a single page.

Primary

Secondary

Use Secondary for less important actions or when multiple actions of the same importance are needed.

For example:

• for Cancel next to a Submit button.
• when needing to let the user do things like Download or Generate a report but neither are the primary focus or goal of the page.

Secondary

Critical

Use Critical when users take an action that is potentially dangerous. For example, when deleting a cluster.

Critical

Tertiary

Use Tertiary for low-priority actions when lighter visual weight is required.

For example:

• for actions on a page that require even less visual weight or priority than a secondary button (our default for less important actions).
• for controlling form fields (such as adding an additional form field).

Tertiary

Icon position

Buttons are provided with flexible icon use; allowing for leading, trailing, or icon only buttons. Use icons intentionally and only when they provide the user with extra value. Do not create buttons with both leading and trailing icons. Tertiary buttons are required to have either a leading or trailing icon layout to be accessible.

Button set

ButtonSets are patterns when multiple Buttons need to be displayed in a single row.

More detailed examples and guidance on button organization can be found in the button organization pattern documentation.

Content

• Text should be short and to the point (~25 characters). Buttons should not consist of full sentences, but should provide enough context to be useful.
• Language should be used consistently within each product (e.g., when using "Edit" on one page, use that same convention throughout the rest of the application, not "Change").

The Button component is used to trigger an action or event. For accessibility, Buttons should not be used to route to a URL; use a Link instead.

How to use this component

The basic invocation requires text to be passed:

<Hds::Button @text="Copy to clipboard" />

Add an icon

To add an icon to your Button, give the @icon any icon name:

<Hds::Button @text="Copy to clipboard" @icon="clipboard-copy" />

Icon position

By default, if you define an icon, it is placed in the leading position (before the text). If you need to position the icon in the trailing position (after the text), define @iconPosition:

<Hds::Button @text="Copy to clipboard" @icon="clipboard-copy" @iconPosition="trailing" />

Icon-only Button

If you would like to create an icon-only Button, set @isIconOnly to true. Note that you still have to define the @text value; it will be used as the aria-label attribute value on the Button element.

<Hds::Button @text="Copy to clipboard" @icon="clipboard-copy" @isIconOnly={{true}} />

Color

There are four available colors for the Button: primary, secondary, tertiary, and critical. The default is primary. To use a different color, declare another value for @color:

<Hds::Button @text="Secondary" @color="secondary" />

<Hds::Button @text="Tertiary" @color="tertiary" @icon="bulb" />

<Hds::Button @text="Critical" @color="critical" />

Size

There are three sizes available for the Button: small, medium, and large. The default is medium. To use a different size, declare a value for @size:

<Hds::Button @text="Small button" @size="small" />

<Hds::Button @text="Large button" @size="large" />

Full-width

This indicates that the Button should take up the full-width of the parent container. It’s set to false by default.

<Hds::Button @text="Copy to clipboard" @isFullWidth={{true}} />

Type

This is the native HTML button attribute, type. There are three possible values: button, submit, and reset. The default type for the Button is submit. To prevent a Button from submitting a form, set type to button.

<Hds::Button @text="Submit" type="submit" />

Actions

Define the action in your route or controller, and add it to the component invocation in your template:

Read the Ember.js guides for more information: Patterns for Actions .

<Hds::Button @text="Copy to clipboard" {{on "click" this.copyToClipboard}} />

Links

You can generate a link with the visual appearance of a button, by passing an @href or a @route argument to the component.

If you’re passing an @href or a @route argument to the component, this will generate an <a> link, not a <button>. In this case, no type is needed.

With @href

If you pass an @href argument, an <a> link will be generated.

target=“_blank” and rel=“noopener noreferrer” attributes are applied by default. This is the most common case, as internal links are generally handled using a @route argument but can be overridden. If the href points to an internal link, or uses a different protocol (e.g., "mailto" of "ftp"), pass @isHrefExternal=true and it will not add the target and rel attributes.

<Hds::Button @text="Visit website" @icon="external-link" @iconPosition="trailing" @href="https://hashicorp.com" />

With @route

If you pass a @route argument, an <a> link will be generated using a <LinkTo> Ember component. All of the standard arguments for the <LinkTo/LinkToExternal> components are supported (eg. models/model/query/current-when/replace).

If the route is external to your current engine, you have to pass @isRouteExternal=true so it will use <LinkToExternal> instead of <LinkTo> for the @route. For more details, see the Hds::Interactive component.

<Hds::Button @text="Back to homepage" @icon="arrow-left" @route="index" />

Disabled Buttons

To disable a Button, manually add the native disabled attribute:

<Hds::Button @text="Copy to clipboard" disabled />

Component API

Anatomy

* One of these must be present.

States

Disabled buttons should be used sparingly and with intention. Acceptable use cases for disabled buttons include:

• Incomplete flows (e.g., user has not yet completed a required action needed to move forward).
• Permissions restriction.

Conformance rating

When used as recommended, there should not be any WCAG conformance issues with this component.

Button vs. link

While buttons and links have been used interchangeably across the internet for years, understanding the difference between these two and striving for the semantic use of these elements can help make our products more conformant.

How to know which to use

• If it goes to a URL, use a Link.
• If it triggers an action (toggles a state, submits a form, etc.), use a Button.
• When submitting a form and redirecting the user to a different URL, use a Button.

Why strive for semantic use

Users with assistive technology (AT) or keyboard-only users rely on the semantic use of Buttons and Links to determine how to activate the element. Buttons are activated with the Enter/Return key or the Spacebar key, while Links can only be activated with the Enter/Return key.

Applicable WCAG Success Criteria

This section is for reference only. This component intends to conform to the following WCAG Success Criteria:

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.