# auro-button AuroButton is a custom element that provides a styled, accessible button with support for various states and form association. It is designed to be flexible, supporting loading states, icon slots, and integration with HTML5 forms. ### Properties & Attributes | Properties | Attributes | Modifiers | Type | Default | Description | | -------------- | ----------- | --------- | ------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | appearance | appearance | | string | `default` | Defines whether the button will be on lighter or darker backgrounds. | | autofocus | autofocus | | boolean | `false` | This Boolean attribute lets you specify that the button should have input focus when the page loads, unless overridden by the user. | | disabled | disabled | | boolean | `false` | If set to true, button will become disabled and not allow for interactions. | | fluid | fluid | | boolean | `false` | Alters the shape of the button to be full width of its parent container. | | formAssociated | | readonly | boolean | | Enables form association for this element. | | layout | layout | | string | `{'default'}` | Override layout since it isn't used in this component. | | loading | loading | | boolean | `false` | If set to true button text will be replaced with `auro-loader` and become disabled. | | loadingText | loadingText | | string | | DEPRECATED - Use `slot="ariaLabel.loading"` instead. | | onDark | ondark | | boolean | `false` | DEPRECATED - use `appearance` attribute. | | shape | shape | | string | `rounded` | Defines the shape of an element. | | size | size | | string | `md` | Defines the size of an element. | | static | static | | boolean | `false` | If true, the button will be static and not respond to user interactions. | | tabindex | tabindex | | string | | Populates `tabindex` to define the focusable sequence in keyboard navigation.
Must be used with "." to ensure the host element does not retain a reference to the `tabindex` attribute.
Example: ``. | | tIndex | tIndex | | string | | Populates `tabindex` to define the focusable sequence in keyboard navigation. | | title | title | | string | | Sets title attribute. The information is most often shown as a tooltip text when the mouse moves over the element. | | value | value | | string | | Defines the value associated with the button which is submitted with the form data. | ### Methods | Name | Parameters | Return | Description | | -------- | -------------------------------------------------------------------- | ------ | ------------------------------------------------- | | register | `name` (string) - The name of the element that you want to register. | | This will register this element with the browser. | ## Basic
Primary Secondary Tertiary Ghost
See code ```html Primary Secondary Tertiary Ghost ``` ## Property & Attribute Examples ### Tab Index For `tabindex`, use `tIndex` instead to avoid duplicated focus interaction. ### Inverse For dark backgrounds, the `inverse` attribute can be applied.
Primary Secondary Tertiary Ghost



See code ```html Primary Secondary Tertiary Ghost



``` ### Disabled The button can be disabled with the `disabled` attribute.
Primary Secondary Tertiary Ghost
See code ```html Primary Secondary Tertiary Ghost ```
Primary Secondary Tertiary Ghost
See code ```html Primary Secondary Tertiary Ghost ``` ### Static The `static` attribute creates a button with no interactivity. When applied, the button becomes non-clickable and serves purely as a visual element. This is useful for displaying button-styled elements that need to appear interactive but should not respond to user input, such as buttons within clickable cards or slides.
Static Primary Button Static Secondary Button Static Tertiary Button

Static Fluid Button

XS Static SM Static MD Static LG Static XL Static

Static Pill with Icon
See code ```html Static Primary Button Static Secondary Button Static Tertiary Button

Static Fluid Button

XS Static SM Static MD Static LG Static XL Static

Static Pill with Icon ```
Static Primary Button Static Secondary Button Static Tertiary Button
See code ```html Static Primary Button Static Secondary Button Static Tertiary Button ``` ### Size The size of the button can be set in t-shirt sizes from `xs` to `xl`
Extra Small Small Medium Large Extra Large
See code ```html Extra Small Small Medium Large Extra Large ``` ### Shape The `shape` attribute defines the shape the button should be. If no `shape` attribute is provided, the button will default to `rounded`. Available options are: - `rounded` - `pill` - `circle` - `square` The `rounded` and `pill` shapes are flexible and can hold any amount of information The `circle` and `square` shapes are always equal dimensions. These shapes currently only support icon-only buttons. #### Rounded
Primary Primary Primary Primary Primary
See code ```html Primary Primary Primary Primary Primary ``` #### Rounded - Toggle Text The `rounded` attribute supports the ability to hide/show the text of the `auro-button`. This can be done by changing the value of the `iconOnly` attribute. In this example, the text is toggled via `mouseover` and `mouseout` events. The `focusin` and `focusout` events simulate toggling text for keyboard users.
arrow-up Text is now shown!
See code ```html arrow-up Text is now shown! ``` ```js export function toggledTextExample() { const toggledTextElem = document.querySelector("#toggledTextElem"); // The mouseover and mouseout events are to simulate toggling text for mouse users toggledTextElem.addEventListener("mouseover", () => { toggledTextElem.shape = "pill"; }); toggledTextElem.addEventListener("mouseout", () => { toggledTextElem.shape = "circle"; }); // The focusin and focusout events are to simulate toggling text for keyboard users toggledTextElem.addEventListener("focusin", () => { toggledTextElem.shape = "pill"; }); toggledTextElem.addEventListener("focusout", () => { toggledTextElem.shape = "circle"; }); } ``` #### Pill
Primary Primary Primary Primary Primary
See code ```html Primary Primary Primary Primary Primary ``` #### Circle
home-filled home-filled home-filled home-filled home-filled
See code ```html home-filled home-filled home-filled home-filled home-filled ``` #### Square
home-filled home-filled home-filled home-filled home-filled
See code ```html home-filled home-filled home-filled home-filled home-filled ``` ### Variant Auro button can use several different variants, including `primary`, `secondary`, `tertiary`, `ghost`, and `flat`. The flat variant should only be used for interface elements that should only have a focus style such as close buttons on dialogs and clear buttons on form elements.
Primary Secondary Tertiary Ghost
See code ```html Primary Secondary Tertiary Ghost ``` ### Fluid In the following example see how the `fluid` attributes alters the shape of the button to be full width of its parent container.
Primary Secondary Tertiary Ghost
See code ```html Primary Secondary Tertiary Ghost ``` ### Right Aligned This example shows a `rounded` `auro-button` that is right-aligned, demonstrating how the button starts from the right and grows/shrinks from right to left when using the `toggleText` attribute in conjuction with the `mouseover` and `mouseout` events. The `focusin` and `focusout` events simulate toggling text for keyboard users.
in-flight Text is now shown!
See code ```html
in-flight Text is now shown!
``` ```js export function roundedRightAlignExample() { const rightAlignElem = document.querySelector("#rightAlignElem"); // The mouseover and mouseout events are to simulate toggling text for mouse users rightAlignElem.addEventListener("mouseover", () => { rightAlignElem.shape = "pill"; }); rightAlignElem.addEventListener("mouseout", () => { rightAlignElem.shape = "circle"; }); // The focusin and focusout events are to simulate toggling text for keyboard users rightAlignElem.addEventListener("focusin", () => { rightAlignElem.shape = "pill"; }); rightAlignElem.addEventListener("focusout", () => { rightAlignElem.shape = "circle"; }); } ``` ### Loading State Use the `loading` attribute to alter the content to the shimmering dots to alert the user that the button/form is in an active state. The `loading` attribute will also place the element in a disabled state to keep the user from re-submitting an action.
Primary Secondary Tertiary Ghost
See code ```html Primary Secondary Tertiary Ghost ```
Primary Secondary Tertiary Ghost
See code ```html Primary Secondary Tertiary Ghost ``` ## Slot Examples ### Icon Support Adding icons to the auro-button component is as easy as nesting any other HTML. The auro-icon component has access to all the icons listed in the Auro Icons library for quick and easy use. Be sure to use the customColor attribute on the `auro-icon` component to allow colors set in your parent element to pass through to the icon and `slot=icon` to properly place the `auro-icon` within the button.
wifi Activate WiFi arrow-left Previous action heart-filled Love this ...
See code ```html wifi Activate WiFi arrow-left Previous action heart-filled Love this ... ``` ### ARIA Support #### Aria Label Accessible text may be provided through the `ariaLabel` or `ariaLabel.loading` slots.
My Button Label Auro Button My Loading Button Label Auro Button
See code ```html My Button Label Auro Button My Loading Button Label Auro Button ``` #### Aria Labelledby The component supports both the `aria-labelledby` attribute for accessibility.
Auro Button
See code ```html Auro Button ``` ## CSS Shadow Part Examples ### Button For buttons without a `buttonHref` attribute, the `button` part will be available.
Primary
See code ```html Primary ``` ### Link For buttons with a `buttonHref` property, the `link` part will be available
Primary
See code ```html Primary ``` ### Content Wrapper
Primary
See code ```html Primary ``` ### Text
Primary
See code ```html Primary ``` ### Loader
Primary
See code ```html Primary ``` ## Common Usage Patterns & Functional Examples ### Pass a Function to Button These examples illustrate a common use case where a user will want to pass a function into a button to support a click event. See the code examples for how this is achieved.
Primary Primary Primary
See code ```html Primary Primary Primary ``` ### Do's and don'ts Don't combine `disabled` and `loading` attributes on any single instance of `auro-button`. An `auro-button` with `loading` *is* affectively a disabled instance. There is no need for both.
Primary Primary
See code ```html Primary Primary ``` ## Restyle Component with CSS Variables The component may be restyled by changing the values of the following token(s). ```scss @use "@aurodesignsystem/design-tokens/dist/themes/alaska/SCSSVariables--alaska" as v; :host { --ds-auro-button-border-color: var(--ds-advanced-color-button-primary-border, #{v.$ds-advanced-color-button-primary-border}); --ds-auro-button-border-inset-color: var(--ds-advanced-color-state-focused-inverse, #{v.$ds-advanced-color-state-focused-inverse}); --ds-auro-button-container-color: var(--ds-advanced-color-button-primary-background, #{v.$ds-advanced-color-button-primary-background}); --ds-auro-button-container-image: var(--ds-advanced-color-button-primary-background, #{v.$ds-advanced-color-button-primary-background}); --ds-auro-button-loader-color: var(--ds-advanced-color-button-primary-text, #{v.$ds-advanced-color-button-primary-text}); --ds-auro-button-text-color: var(--ds-advanced-color-button-primary-text, #{v.$ds-advanced-color-button-primary-text}); } ```