Button

Buttons are used primarily for actions, such as “Add”, “Close”, “Cancel”, or “Save”. Plain buttons, which look similar to links, are used for less important or less commonly used actions, such as “view additional details“.

The default form of a button, used for most cases. They are not impactful enough to represent the primary action in a container.

<ahi-button>Default button</ahi-button>

        
  
        
      

Examples

Primary

Use a primary button to call attention to an action on a form or to highlight the strongest call to action on a page. Primary buttons should only appear once per container (not including the application header or in a modal dialog). Not every screen requires a primary button.

<ahi-button variant="primary">Primary button</ahi-button>

        
  
        
      

Destructive

The destructive button appears as a final confirmation for a destructive action such as deleting. These are found mostly in confirmation modals.

<ahi-button variant="destructive">Destructive button</ahi-button>

        
  
        
      

Sizes

Use the size attribute to change a button’s size.

<ahi-button size="small">Small button</ahi-button>
<ahi-button size="medium">Medium button</ahi-button>
<ahi-button size="large">Large button</ahi-button>

        
  
        
      

Plain buttons

Use plain buttons for less important or less commonly used actions since they’re less prominent. For example, plain buttons are used as actions in cards.

A plain button is still a button: it keeps its padding and minimum height, so it doesn’t fit inside a sentence. For navigation, or for a link in or after a sentence, use the ahi-link class instead of restyling a plain button: on an <a> for navigation, or on a <button type="button"> for an action inside a sentence.

<ahi-button plain>Plain button</ahi-button>

        
  
        
      

Outline buttons

Use outline buttons against shaded or colorful backgrounds. An outline button will maintain the appropriate visual weight and won’t clash with the background color.

<ahi-button outline>Default button</ahi-button>
<ahi-button variant="primary" outline>Primary button</ahi-button>
<ahi-button variant="destructive" outline>Destructive button</ahi-button>

        
  
        
      

States

Disabled

Use for actions that aren’t currently available. The surrounding interface should make it clear why the button is disabled and what needs to be done to enable it.

<ahi-button variant="primary" disabled>Disabled button</ahi-button>
<ahi-button variant="destructive" disabled>Disabled button</ahi-button>
<ahi-button outline disabled>Disabled button</ahi-button>
<ahi-button plain disabled>Disabled button</ahi-button>
<ahi-button variant="destructive" plain disabled>Disabled button</ahi-button>

        
  
        
      

Loading

Use when a button has been pressed and the associated action is in progress.

<ahi-button variant="primary" loading>Loading button</ahi-button>

        
  
        
      

Link buttons

It’s often helpful to have a button that works like a link. This is possible by setting the href attribute, which will make the component render an <a> under the hood. This gives you all the default link behavior the browser provides (e.g. CMD/CTRL/SHIFT + CLICK) and exposes the target and download attributes.

<ahi-button href="https://example.com/" target="_blank">Link button</ahi-button>

        
  
        
      

Full width

Use for buttons placed in a narrow column (especially when stacking multiple buttons) or for creating a set of buttons of equal width. Full-width buttons should rarely exceed 320 px wide.

<ahi-button style="width: 100%;">Full width button</ahi-button>

        
  
        
      

Button with icons

Buttons may include an icon before or after the text. Use the prefix and suffix slots to add icons.

<!-- Icon before -->
<ahi-button>
  <ahi-icon slot="prefix" name="settings" size="minor"></ahi-icon>
  Settings
</ahi-button>

<!-- Icon after -->
<ahi-button>
  <ahi-icon slot="suffix" name="refresh" size="minor"></ahi-icon>
  Refresh
</ahi-button>


        
  
        
      

Disclosure

Use the disclosure attribute to add a dropdown indicator when a button will trigger a dropdown, menu, or select.

<div style="display: flex; gap: var(--ahi-space-2)">
  <ahi-button disclosure>Dropdown</ahi-button>
  <ahi-button disclosure="up">Dropdown</ahi-button>
  <ahi-button disclosure="select">Select</ahi-button>
</div>

        
  
        
      

Showing and hiding content

When a button shows and hides a section of the page, set aria-expanded on the button, set aria-controls to the section’s id, and update aria-expanded each time the section opens or closes. The button passes both to the <button> it renders, which is the element screen readers announce, so they say whether the section is open. It passes aria-controls as a reference to the section itself, because an id can’t be found from inside the shadow root, so the internal <button>’s own aria-controls attribute reads empty in the browser’s developer tools. The id must be in the same document or shadow root as the button. A section added to the page after the button is linked the next time the button updates or takes focus.

A button that triggers an <ahi-dropdown> or <ahi-popover> doesn’t need aria-expanded: the dropdown or popover sets it, with aria-haspopup, as soon as it has rendered, and updates it as it opens and closes. That holds for the button placed directly in the trigger or anchor slot; when it is wrapped in another element there, the dropdown or popover sets them on the wrapper instead, and the button gets neither.

<ahi-button class="button-disclosure" disclosure aria-expanded="false" aria-controls="button-disclosure-filters">
  Filters
</ahi-button>

<div id="button-disclosure-filters" hidden>
  <p>Show only visits from the last 30 days.</p>
</div>

<script>
  const button = document.querySelector('.button-disclosure');
  const filters = document.getElementById('button-disclosure-filters');

  button.addEventListener('click', () => {
    const open = button.getAttribute('aria-expanded') !== 'true';
    button.setAttribute('aria-expanded', String(open));
    button.disclosure = open ? 'up' : 'down';
    filters.hidden = !open;
  });
</script>

        
  
        
      

Custom styling

This example demonstrates how to style buttons using a custom class. This is the recommended approach if you need to add additional variations. To customize an existing variation, modify the selector to target the button’s variant attribute instead of a class (e.g. ahi-button[variant="primary"]).

<ahi-button class="magenta">Button</ahi-button>

<style>
  ahi-button.magenta::part(base) {
    background: linear-gradient(
      15deg,
      var(--ahi-brand-navy),
      var(--ahi-color-purple-700),
      var(--ahi-color-purple-400),
      var(--ahi-color-purple-50)
    );
    border-radius: var(--ahi-border-radius-medium);
  }

  ahi-button.magenta::part(base):hover {
    filter: brightness(90%);
  }

  ahi-button.magenta::part(base):active {
    filter: brightness(75%);
  }

  ahi-button.magenta::part(label) {
    color: var(--ahi-text-on-primary);
    font-size: 1.25rem;
  }
</style>

        
  
        
      

Keyboard support

• Give buttons focus with the tab key (or shift + tab when tabbing backwards)
• Activate buttons with the enter / return key or the space key

Best practices

Buttons should:

• Be clearly and accurately labeled.
• Lead with a strong, actionable verb.
• Use established button colors appropriately. For example, only use a danger button style for an action that’s difficult or impossible to undo.
• Prioritize the most important actions. Too many buttons can cause confusion.
• Be consistent with the positioning of buttons in the interface. See Order of actions.

Order of actions

Rank a row’s actions first: one primary action (variant="primary"), then secondary actions (the default button), then tertiary actions (plain). Then put the primary action at the edge the row is aligned to, so people find it in the same place on every screen.

• Keep the source order the same as the order on screen. Keyboard focus and screen readers follow the source, so don’t move the primary action with flex-direction: row-reverse or order.
• When a row stacks into full-width buttons on a narrow screen, put the primary action on top. For an end-aligned row that takes flex-direction: column-reverse, the one place the order on screen may differ from the source.
• Use one primary action per row.
• When a row confirms an action that can’t be undone, like Delete in a delete dialog, the destructive button takes the primary position and Cancel is secondary.
• Back and Next keep their direction whatever the alignment: Back at the start, Next at the end.
• In a row that spans the full width, a tertiary action such as Clear all can sit alone at the start edge, with the other actions at the end.

A card footer is end-aligned by default:

<ahi-card title="Secure your account with 2-step authentication">
  <ahi-card-section>Two-step authentication asks for a code at every sign-in, so only you can get into your account.</ahi-card-section>
  <ahi-button slot="footer-actions" plain>Learn more</ahi-button>
  <ahi-button slot="footer-actions">Not now</ahi-button>
  <ahi-button slot="footer-actions" variant="primary">Turn on</ahi-button>
</ahi-card>

        
  
        
      

Form buttons line up with the fields above them, so the row is start-aligned:

<div class="ahi-column ahi-gap-4" style="max-width: 24rem">
  <ahi-input label="Preferred name"></ahi-input>
  <div class="ahi-row ahi-gap-2">
    <ahi-button variant="primary">Save</ahi-button>
    <ahi-button>Cancel</ahi-button>
  </div>
</div>

        
  
        
      

Buttons vs links

Buttons are used primarily for actions, such as “Add”, “Close”, “Cancel”, or “Save”.

Links are used primarily for navigation, and usually appear within or directly following a sentence. Style them with the ahi-link class, which takes the surrounding font so the link wraps with the sentence.

The HTML that renders for the button component and anchor tags carry meaning. Using these intentionally and consistently results in:

• a more inclusive experience for assistive technology users
• a more cohesive visual experience for sighted users
• products that are easier to maintain at scale

Content guidelines

• Always write button text in sentence case, which means the first word is capitalized and the rest are lowercase (unless a term is a proper noun).
• Avoid unnecessary words and articles such as “the,” “an,” or “a.”

Related components

• To combine or lay out multiple buttons, use the button group component
• For navigational actions that appear within or directly following a sentence, use <a> (anchor) tags.

Importing

<script type="module" src="/path/to/azalea-kit-ui/dist/components/button/button.js"></script>
        
  
        
      

import '@azaleahealth/azalea-kit-ui/dist/components/button/button.js';
        
  
        
      

Slots

Learn more about using slots.

Properties

Learn more about properties and attributes.

Events

Learn more about events.

Methods

Learn more about methods.

CSS Parts

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

• <ahi-icon>
• <ahi-spinner>