Button

Usage

When to use

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

When not to use

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

Sizes

Small

Medium

Large

Full-width button

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

Buttons are able to be manually stretched to accommodate a need for a full-width button. Full-width buttons should fill 100% of the parent container.

Types

Primary

Primary

Use Primary for the most important action on a page. Avoid using multiple Primary buttons on a page.

For example:

• for submitting a form

  Secondary

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

  Critical

Critical

Use Critical when users take an action that is potentially dangerous.

For example:

• deleting a cluster.

Tertiary

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)

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

Button Sets are patterns when multiple buttons need to be displayed in a single row; not to be confused with Button Groups.

Primary buttons are displayed on the left, Secondary or Tertiary buttons on the right, with 16px between them.

Content

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

How to use this component

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.

Basic use

The most 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 before the text. If you would like to position the icon 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}} />

Note: If you need to add a tooltip to an icon-only button, here is an example of how to do it in an accessible way: Accessible Button Tooltip Pattern.

Color

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

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

Size

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

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

Full-width

This allows indication that a button should take up the full-width of the parent container. It is set to false by default.

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

Type

This is the native 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" />

Notice: if you’re passing a @href or a @route argument to the component, this will generate a <a> link, not a <button> (see below). In this case no type is needed.

Actions

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

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

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

Links

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

With @href

If you pass a @href argument a <a> link will be generated:

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

Important: when using the @href argument the component adds by default the attributes target="_blank" and rel="noopener noreferrer" to the <a> element (because this is the most common use case: internal links are generally handled using a @route argument). If the href points to an internal link, or uses a different protocol (eg. "mailto" of "ftp") you can pass @isHrefExternal=true to the component and it will not add the target and rel attributes (but you can pass yours if needed, using the ...attributes spreading. For more details see the Hds::Interactive component.

Important: if a href HTML attribute is used instead of the @href Ember argument we apply this visual treatment to alert the developer:

With @route

If you pass a @route argument a <a> link will be generated using a <LinkTo> Ember component:

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

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

Disabled buttons

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

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

Notice: since a <a> link can’t be disabled, if you’re passing a @href or a @route argument to the component you will need to take care of intercepting the events in case you want to disable it.

Component API

Anatomy

* One of these must be present.

States

Primary

Secondary

Tertiary

Critical

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

• Incomplete flows (ie. 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.

Accessibility in design

Provide annotations alongside each design of the non-visual experience. This could look like:

Accessibility considerations

Years of misuse have muddled the purpose of a button element vs. a link element, so here is a good rule of thumb to follow:

If it goes to a URL, use a link. If it does an action (toggles a state, submits a form, etc.), then use a button.

Now, you may be thinking, “What about instances where I submit a form and redirect a user to a different URL?” This is still a button use case.

Buttons and links especially make a difference for keyboard-only users and users with assistive technology (AT). A button element can be activated with the Enter/Return key or the Spacebar; a link can only be activated with the Enter/Return key.

If you are working on a UI that already uses buttons and links interchangeably, this is a great opportunity for a team discussion on which one is appropriate for use in your situation. It’s totally okay for it to be a goal that you work toward; there are always opportunities to care for, and improve, our code.

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.