Button component - How to use
The button component is used to trigger an action or event. For accessibility, buttons should not be used to route to a URL.
Basic use
The most basic invocation requires text to be passed:
<Hds::Button @text="Copy to clipboard" />
Renders to:
Add an icon
To add an icon to your button, give the
@icon
a
Flight icon
name:
<Hds::Button @text="Copy to clipboard" @icon="clipboard-copy" />
Renders to:
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" />
Renders to:
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= />
Renders to:
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" />
Renders to:
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" />
Renders to (with icons):
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= />
Renders to:
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" />
Read the Ember.js guides for more information: Patterns for Actions .
Links
You can generate a link with the visual appearence of a button passing a
@href
or a
@route
argument to the component.
Notice: the
Hds::Button
component internally uses the generic
Hds::Interactive
component. For more details about how this low-level component works please refer to
its documentation page.
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" />
Renders to:
⚠️
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.
🚨
Notice: 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:
Renders to:
⚠️
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.
Notice: all the standard arguments for the
<LinkTo/LinkToExternal>
components are supported (eg.
models/model/query/current-when/replace).
Disabled buttons
To disable a button, manually add the native
disabled
attribute:
<Hds::Button @text="Copy to clipboard" disabled />
Renders to:
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.