Skip to main content

Button

A button helps me submit an online form, find important links, or turn something on.

The Button component allows users to trigger actions. They are styled consistently according to their importance and the type of action they enable the user to perform.

Details

Extends: USWDS Button component
Honeycrisp: Button atom
Customization: Design tokens and Styles
Modifier: .cfa-button

The Button extends the USWDS Button component. The visual appearance is modified using design tokens applied to the USWDS Button component settings from the Honeycrisp Button atom. Further customization is applied using the CSS modifier(s) .cfa-button to add styles defined in a custom stylesheet.

Design tokens. Tokens define the name of basic system elements such as color, typography, or spacing. The values of tokens are relative to how the system defines them. This enables teams to alter the visual appearance of components yet remain within the system boundaries. Learn more about tokens on the Bixal's Design Tokens Guide.

Modifier. A modifier is a class name that applies a variant, type, or extended style customization to modify the component's visual appearance.

Examples

Primary button

View HTML

The HTML for the demonstration above is rendered using context passed to the component's Thymeleaf template fragment. Learn how to include component templates for Thymeleaf and Ruby in the source and usage section.

<button class="usa-button cfa-button" type="button">
  <span>Primary</span>
</button>
<button class="usa-button cfa-button" type="button" disabled="true">
  <span>Disabled</span>
</button>
<button class="usa-button cfa-button" type="button" aria-disabled="true">
  <span>ARIA Disabled</span>
</button>

View context passed to this component

Context is the information necessary to configure and render a component template to HTML. It may include plain text strings, HTML, class names, IDs or other HTML attribute values. The context here is defined as JSON but the root attributes are translated to different variable syntaxes for Thymeleaf and Ruby templates. Learn how to pass these variables to each component template in the source and usage section.

{
  "items": [
    {
      "label": "Primary",
      "modifier": "cfa-button",
      "type": "button"
    },
    {
      "label": "Disabled",
      "modifier": "cfa-button",
      "type": "button",
      "disabled": "true"
    },
    {
      "label": "ARIA Disabled",
      "modifier": "cfa-button",
      "type": "button",
      "ariaDisabled": "true"
    }
  ]
}

Outline button

View HTML

The HTML for the demonstration above is rendered using context passed to the component's Thymeleaf template fragment. Learn how to include component templates for Thymeleaf and Ruby in the source and usage section.

<button class="usa-button cfa-button usa-button--outline" type="button">
  <span>Outline</span>
</button>
<button class="usa-button cfa-button usa-button--outline" type="button" disabled="true">
  <span>Disabled</span>
</button>
<button class="usa-button cfa-button usa-button--outline" type="button" aria-disabled="true">
  <span>ARIA Disabled</span>
</button>

View context passed to this component

Context is the information necessary to configure and render a component template to HTML. It may include plain text strings, HTML, class names, IDs or other HTML attribute values. The context here is defined as JSON but the root attributes are translated to different variable syntaxes for Thymeleaf and Ruby templates. Learn how to pass these variables to each component template in the source and usage section.

{
  "items": [
    {
      "label": "Outline",
      "modifier": "cfa-button usa-button--outline",
      "type": "button"
    },
    {
      "label": "Disabled",
      "modifier": "cfa-button usa-button--outline",
      "type": "button",
      "disabled": "true"
    },
    {
      "label": "ARIA Disabled",
      "modifier": "cfa-button usa-button--outline",
      "type": "button",
      "ariaDisabled": "true"
    }
  ]
}

Big button

View HTML

The HTML for the demonstration above is rendered using context passed to the component's Thymeleaf template fragment. Learn how to include component templates for Thymeleaf and Ruby in the source and usage section.

<button class="usa-button cfa-button usa-button--big" type="button">
  <span>Big Primary</span>
</button>
<button class="usa-button cfa-button usa-button--big" type="button" disabled="true">
  <span>Disabled</span>
</button>
<button class="usa-button cfa-button usa-button--big" type="button" aria-disabled="true">
  <span>ARIA Disabled</span>
</button>

View context passed to this component

Context is the information necessary to configure and render a component template to HTML. It may include plain text strings, HTML, class names, IDs or other HTML attribute values. The context here is defined as JSON but the root attributes are translated to different variable syntaxes for Thymeleaf and Ruby templates. Learn how to pass these variables to each component template in the source and usage section.

{
  "items": [
    {
      "label": "Big Primary",
      "modifier": "cfa-button usa-button--big",
      "type": "button"
    },
    {
      "label": "Disabled",
      "modifier": "cfa-button usa-button--big",
      "type": "button",
      "disabled": "true"
    },
    {
      "label": "ARIA Disabled",
      "modifier": "cfa-button usa-button--big",
      "type": "button",
      "ariaDisabled": "true"
    }
  ]
}

Big outline button

View HTML

The HTML for the demonstration above is rendered using context passed to the component's Thymeleaf template fragment. Learn how to include component templates for Thymeleaf and Ruby in the source and usage section.

<button class="usa-button cfa-button usa-button--big usa-button--outline" type="button">
  <span>Big Outline</span>
</button>
<button class="usa-button cfa-button usa-button--big usa-button--outline" type="button" disabled="true">
  <span>Disabled</span>
</button>
<button class="usa-button cfa-button usa-button--big usa-button--outline" type="button" aria-disabled="true">
  <span>ARIA Disabled</span>
</button>

View context passed to this component

Context is the information necessary to configure and render a component template to HTML. It may include plain text strings, HTML, class names, IDs or other HTML attribute values. The context here is defined as JSON but the root attributes are translated to different variable syntaxes for Thymeleaf and Ruby templates. Learn how to pass these variables to each component template in the source and usage section.

{
  "items": [
    {
      "label": "Big Outline",
      "modifier": "cfa-button usa-button--big usa-button--outline",
      "type": "button"
    },
    {
      "label": "Disabled",
      "modifier": "cfa-button usa-button--big usa-button--outline",
      "type": "button",
      "disabled": "true"
    },
    {
      "label": "ARIA Disabled",
      "modifier": "cfa-button usa-button--big usa-button--outline",
      "type": "button",
      "ariaDisabled": "true"
    }
  ]
}

Button with icons. Any butt, dictionary: dictionary n type may have a prefixed or postfixed icon inside the label.

View HTML

The HTML for the demonstration above is rendered using context passed to the component's Thymeleaf template fragment. Learn how to include component templates for Thymeleaf and Ruby in the source and usage section.

<button class="usa-button cfa-button" type="button">
  <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
    <use href="https://codeforamerica.github.io/uswds/assets/img/sprite.svg#translate"></use>
  </svg>
  <span>Button</span>
</button>
<button class="usa-button cfa-button">
  <span>Button</span>
  <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
    <use href="https://codeforamerica.github.io/uswds/assets/img/sprite.svg#arrow_forward"></use>
  </svg>
</button>
<button class="usa-button cfa-button usa-button--big">
  <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
    <use href="https://codeforamerica.github.io/uswds/assets/img/sprite.svg#translate"></use>
  </svg>
  <span>Button</span>
</button>
<button class="usa-button cfa-button usa-button--big">
  <span>Button</span>
  <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
    <use href="https://codeforamerica.github.io/uswds/assets/img/sprite.svg#arrow_forward"></use>
  </svg>
</button>

<button class="usa-button cfa-button" type="button">
  <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
    <use href="https://codeforamerica.github.io/uswds/assets/img/sprite.svg#translate"></use>
  </svg>
  <span>Button</span>
</button>
<button class="usa-button cfa-button">
  <span>Button</span>
  <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
    <use href="https://codeforamerica.github.io/uswds/assets/img/sprite.svg#arrow_forward"></use>
  </svg>
</button>
<button class="usa-button cfa-button usa-button--big">
  <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
    <use href="https://codeforamerica.github.io/uswds/assets/img/sprite.svg#translate"></use>
  </svg>
  <span>Button</span>
</button>
<button class="usa-button cfa-button usa-button--big">
  <span>Button</span>
  <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
    <use href="https://codeforamerica.github.io/uswds/assets/img/sprite.svg#arrow_forward"></use>
  </svg>
</button>

View context passed to this component

The context here is defined as JSON but the root attributes are translated to different variable syntaxes for Thymeleaf and Ruby templates. Learn how to pass these variables to each component template in the source and usage section.

{
  "items": [
    {
      "label": "Button",
      "modifier": "cfa-button",
      "type": "button",
      "prefix": "https://codeforamerica.github.io/uswds/assets/img/sprite.svg#translate"
    },
    {
      "label": "Button",
      "modifier": "cfa-button",
      "postfix": "https://codeforamerica.github.io/uswds/assets/img/sprite.svg#arrow_forward"
    },
    {
      "label": "Button",
      "modifier": "cfa-button usa-button--big",
      "prefix": "https://codeforamerica.github.io/uswds/assets/img/sprite.svg#translate"
    },
    {
      "label": "Button",
      "modifier": "cfa-button usa-button--big",
      "postfix": "https://codeforamerica.github.io/uswds/assets/img/sprite.svg#arrow_forward"
    }
  ]
}

Unstyled button

View HTML

The HTML for the demonstration above is rendered using context passed to the component's Thymeleaf template fragment. Learn how to include component templates for Thymeleaf and Ruby in the source and usage section.

<button class="usa-button usa-button--unstyled" type="button">
  <span>Unstyled</span>
</button>
<button class="usa-button usa-button--unstyled" type="button" disabled="true">
  <span>Disabled</span>
</button>
<button class="usa-button usa-button--unstyled" type="button" aria-disabled="true">
  <span>ARIA Disabled</span>
</button>

View context passed to this component

Context is the information necessary to configure and render a component template to HTML. It may include plain text strings, HTML, class names, IDs or other HTML attribute values. The context here is defined as JSON but the root attributes are translated to different variable syntaxes for Thymeleaf and Ruby templates. Learn how to pass these variables to each component template in the source and usage section.

{
  "items": [
    {
      "label": "Unstyled",
      "modifier": "usa-button--unstyled",
      "type": "button"
    },
    {
      "label": "Disabled",
      "modifier": "usa-button--unstyled",
      "type": "button",
      "disabled": "true"
    },
    {
      "label": "ARIA Disabled",
      "modifier": "usa-button--unstyled",
      "type": "button",
      "ariaDisabled": "true"
    }
  ]
}

Secondary button

View HTML

The HTML for the demonstration above is rendered using context passed to the component's Thymeleaf template fragment. Learn how to include component templates for Thymeleaf and Ruby in the source and usage section.

<button class="usa-button cfa-button usa-button--secondary" type="button">
  <span>Secondary</span>
</button>
<button class="usa-button cfa-button usa-button--secondary usa-button--big" type="button">
  <span>Big Secondary</span>
</button>

View context passed to this component

Context is the information necessary to configure and render a component template to HTML. It may include plain text strings, HTML, class names, IDs or other HTML attribute values. The context here is defined as JSON but the root attributes are translated to different variable syntaxes for Thymeleaf and Ruby templates. Learn how to pass these variables to each component template in the source and usage section.

{
  "items": [
    {
      "label": "Secondary",
      "modifier": "cfa-button usa-button--secondary",
      "type": "button"
    },
    {
      "label": "Big Secondary",
      "modifier": "cfa-button usa-button--secondary usa-button--big",
      "type": "button"
    }
  ]
}

Danger buttons tell users to pause and ensure they’re certain of the action they’re about to take. It can be a way to signal that action is discouraged (e.g., submitting a minimal application anyway) or irreversible (e.g., deleting a client or removing document).

View HTML

The HTML for the demonstration above is rendered using context passed to the component's Thymeleaf template fragment. Learn how to include component templates for Thymeleaf and Ruby in the source and usage section.

<button class="usa-button cfa-button cfa-button--danger" type="button">
  <span>Danger</span>
</button>
<button class="usa-button cfa-button cfa-button--danger usa-button--big" type="button">
  <span>Danger</span>
</button>
<button class="usa-button cfa-button cfa-button--danger usa-button--outline" type="button">
  <span>Danger</span>
</button>
<button class="usa-button cfa-button cfa-button--danger usa-button--outline usa-button--big" type="button">
  <span>Danger</span>
</button>
<button class="usa-button cfa-button cfa-button--danger usa-button--unstyled" type="button">
  <span>Danger</span>
</button>

View context passed to this component

Context is the information necessary to configure and render a component template to HTML. It may include plain text strings, HTML, class names, IDs or other HTML attribute values. The context here is defined as JSON but the root attributes are translated to different variable syntaxes for Thymeleaf and Ruby templates. Learn how to pass these variables to each component template in the source and usage section.

{
  "items": [
    {
      "label": "Danger",
      "modifier": "cfa-button cfa-button--danger",
      "type": "button"
    },
    {
      "label": "Danger",
      "modifier": "cfa-button cfa-button--danger usa-button--big",
      "type": "button"
    },
    {
      "label": "Danger",
      "modifier": "cfa-button cfa-button--danger usa-button--outline",
      "type": "button"
    },
    {
      "label": "Danger",
      "modifier": "cfa-button cfa-button--danger usa-button--outline usa-button--big",
      "type": "button"
    },
    {
      "label": "Danger",
      "modifier": "cfa-button cfa-button--danger usa-button--unstyled",
      "type": "button"
    }
  ]
}

Link button

Internal Link External Link ARIA Disabled

View HTML

The HTML for the demonstration above is rendered using context passed to the component's Thymeleaf template fragment. Learn how to include component templates for Thymeleaf and Ruby in the source and usage section.

<a class="usa-button cfa-button usa-button--outline" href="#">
  <span>Internal Link</span>
  <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
    <use href="https://codeforamerica.github.io/uswds/assets/img/sprite.svg#arrow_forward"></use>
  </svg>
</a>
<a class="usa-button cfa-button usa-button--outline" href="#">
  <span>External Link</span>
  <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
    <use href="https://codeforamerica.github.io/uswds/assets/img/sprite.svg#launch"></use>
  </svg>
</a>
<a class="usa-button cfa-button usa-button--outline" aria-disabled="true" href="#">
  <span>ARIA Disabled</span>
  <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
    <use href="https://codeforamerica.github.io/uswds/assets/img/sprite.svg#launch"></use>
  </svg>
</a>

View context passed to this component

Context is the information necessary to configure and render a component template to HTML. It may include plain text strings, HTML, class names, IDs or other HTML attribute values. The context here is defined as JSON but the root attributes are translated to different variable syntaxes for Thymeleaf and Ruby templates. Learn how to pass these variables to each component template in the source and usage section.

{
  "items": [
    {
      "label": "Internal Link",
      "modifier": "cfa-button usa-button--outline",
      "href": "#",
      "postfix": "https://codeforamerica.github.io/uswds/assets/img/sprite.svg#arrow_forward"
    },
    {
      "label": "External Link",
      "modifier": "cfa-button usa-button--outline",
      "href": "#",
      "postfix": "https://codeforamerica.github.io/uswds/assets/img/sprite.svg#launch"
    },
    {
      "label": "ARIA Disabled",
      "modifier": "cfa-button usa-button--outline",
      "href": "#",
      "postfix": "https://codeforamerica.github.io/uswds/assets/img/sprite.svg#launch",
      "ariaDisabled": "true"
    }
  ]
}

Guidance

Type attribute. If the button is a <button> element the type attribute should be explicitly set to “button,” “reset,” or “submit.” Without the type attribute, button elements are set to the “submit” type in forms by default.

Links as buttons. Links may be styled as buttons. However, screen readers will distinguish between links and buttons differently regardless of how they are styled. Normally, the keyboard can only invoke links using the Enter key. However, when users press the Space key, the USWDS will open links styled as buttons (with JavaScript). A consistent button variant should still be used to distinguish between buttons that open links and buttons that invoke actions. Consider using an icon for buttons styled as links, such as directional arrows for onsite links, and an external icon for links that go offsite.

Labels. Buttons should always include a text label but may also include an icon prefix or postfix on either side of the label. Buttons with an icon but without text labels are discouraged. The icon and text label combination is the most certain way of communicating the icon's meaning.

Button role. Buttons should be written using the <button> element. However, if a button is a different element styled as a button and performs an action, the role attribute should be set to role=”button”.

Disabling buttons. To achieve the effect of disabling buttons or links styled as buttons but provide context to screen readers as to why it's disabled, use the following pattern.

Use the ARIA disabled attribute aria-disabled=”true” instead of the disabled attribute.
Prevent events such as form submissions and clicks on the button using JavaScript.
Provide an aria-describedby attribute that points to an element’s id with text indicating why the button is disabled.

Refer to additional guidance on the USWDS documentation site.

USWDS documentation site

Additional references

Accessibility

Customization to the visual appearance of the Button has been verified for WCAG 2.1 AA contrast minimum success.
The Button examples pass manual audits (WCAG 2.1 AA using axe or Lighthouse).
The Button achieves WCAG 2.1 AA resizing success.
Resizing text up to 200% without loss of content or functionality.
The Button passes keyboard interaction tests.
When navigating to any button using the keyboard, a visible focus indicator (WCAG 2.1 AA success) is present. Buttons and links styled as buttons can be activated using the space bar.
The Button passes screen reader interaction tests.
Guidance on ensuring Button accessibility has been provided in this documentation.

Additional items

Vertical padding (top and bottom) on the smallest Button size has been increased to 2 spacing units to achieve WCAG 2.1 AAA target size success requirements.

Refer to additional accessibility guidance on the USWDS documentation site.

Checklist Key

Passes
Unchecked

Design library component

Source and usage

Package: @codeforamerica/uswds/packages/cfa-button

Sass stylesheet: ./_cfa-button.scss
Thymeleaf template fragment: ./cfa-button.th.html
Embedded Ruby (ERB) partial template: ./_cfa-button.html.erb
JavaScript enables links that are styled as buttons to be invoked using the space bar. Guidance on individual module loading will added. Currently, there is one script that imports all modules. The source is located at @codeforamerica/js/index.js. This entrypoint is compiled using Rollup.js and distributed to @codeforamerica/dist/js/default.js.

Packages are collections of functionality that make up a component. Typically, they include stylesheets, templates, and scripts. Learn more about packages on the USWDS documentation site.

Sass theme settings

Below is a demonstration of customizing the component theme settings. Refer to the theme and package-level settings documentation.

// Theme-level settings
@use 'cfa-uswds-theme' with (
  // Global theme settings that affect the component, changing these will affect other components
  $cfa-color-base-lightest: 'gray-warm-4',    // Affects outline button hover state
  $cfa-color-base-lighter: 'gray-warm-10',    // Affects disabled button state
  $cfa-color-base-ink: 'gray-warm-90',        // Affects outline button
  $cfa-color-primary: 'mint-50',              // Affects primary button state
  $cfa-color-primary-darker: 'mint-cool-80v', // Affects primary button hover state
  $cfa-color-secondary: 'magenta-50v',        // Affects the secondary button
  $cfa-color-secondary-darker: 'magenta-70v', // Affects the secondary button hover state
  $cfa-color-error: 'orange-warm-50v',        // Affects the danger button, the no button icon color
  $cfa-color-error-darker: 'orange-warm-70v', // Affects the danger button hover state
  $cfa-color-disabled-light: 'gray-warm-10',  // Affects disabled button
  $cfa-color-disabled: 'gray-warm-50',        // Affects disabled outline button
  $cfa-color-disabled-dark: 'gray-warm-70',   // Affects disabled button text
);
// Package-level settings
@use 'cfa-core' with (
  $cfa-button-big-font-size: 'lg',
  $cfa-button-big-border-radius: 'lg',
);

// Theme-level settings
@use 'cfa-uswds-theme' with (
  // Global theme settings that affect the component, changing these will affect other components
  $cfa-color-base-lightest: 'gray-warm-4',    // Affects outline button hover state
  $cfa-color-base-lighter: 'gray-warm-10',    // Affects disabled button state
  $cfa-color-base-ink: 'gray-warm-90',        // Affects outline button
  $cfa-color-primary: 'mint-50',              // Affects primary button state
  $cfa-color-primary-darker: 'mint-cool-80v', // Affects primary button hover state
  $cfa-color-secondary: 'magenta-50v',        // Affects the secondary button
  $cfa-color-secondary-darker: 'magenta-70v', // Affects the secondary button hover state
  $cfa-color-error: 'orange-warm-50v',        // Affects the danger button, the no button icon color
  $cfa-color-error-darker: 'orange-warm-70v', // Affects the danger button hover state
  $cfa-color-disabled-light: 'gray-warm-10',  // Affects disabled button
  $cfa-color-disabled: 'gray-warm-50',        // Affects disabled outline button
  $cfa-color-disabled-dark: 'gray-warm-70',   // Affects disabled button text
);
// Package-level settings
@use 'cfa-core' with (
  $cfa-button-big-font-size: 'lg',
  $cfa-button-big-border-radius: 'lg',
);

USWDS theme settings

Refer to the usage documentation for additional USWDS theme settings.

@use "uswds-core" with ( /* additional USWDS theme settings */ );

Thymeleaf template fragment

This is the pre-rendered template fragment from the package. It is the same template used to render the demonstrations above. You may copy and paste from this example or use the template using the th:block th:replace tag. See the example below.

<th:block th:fragment="button(items)" th:each="button: ${items}">
  <button th:unless="${button.href}" class="usa-button" th:classappend="${button.modifier}" th:attr="type=${button.type},disabled=${button.disabled},aria-disabled=${button.ariaDisabled}">
    <svg th:if="${button.check}" class="usa-icon" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" role="img">
      <path d="M3.5 9.42857L0 13L8 22L22 3.5L18 0L7.5 14L3.5 9.42857Z" fill="inherit"/>
    </svg>
    <svg th:if="${button.cross}" class="usa-icon" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" role="img">
      <path d="M14.667 11.0009L22 3.66696L18.3335 0L11 7.33392L3.66696 0.00088L0 3.66696L7.33348 11L0 18.3339L3.6674 22L11.0004 14.667L18.3335 22L22 18.3339L14.667 11.0009Z" fill="inherit"/>
    </svg>
    <svg th:if="${button.prefix}" class="usa-icon" aria-hidden="true" focusable="false" role="img">
      <use th:href="${button.prefix}"></use>
    </svg>
    <span th:text="${button.label}">Label</span>
    <svg th:if="${button.postfix}" class="usa-icon" aria-hidden="true" focusable="false" role="img">
      <use th:href="${button.postfix}"></use>
    </svg>
  </button>
  <a th:if="${button.href}" th:href="${button.href}" class="usa-button" th:classappend="${button.modifier}" th:attr="role=${button.role},disabled=${button.disabled},aria-disabled=${button.ariaDisabled},target=${button.target},rel=${button.rel}">
    <svg th:if="${button.check}" class="usa-icon" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" role="img">
      <path d="M3.5 9.42857L0 13L8 22L22 3.5L18 0L7.5 14L3.5 9.42857Z" fill="inherit"/>
    </svg>
    <svg th:if="${button.cross}" class="usa-icon" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" role="img">
      <path d="M14.667 11.0009L22 3.66696L18.3335 0L11 7.33392L3.66696 0.00088L0 3.66696L7.33348 11L0 18.3339L3.6674 22L11.0004 14.667L18.3335 22L22 18.3339L14.667 11.0009Z" fill="inherit"/>
    </svg>
    <svg th:if="${button.prefix}" class="usa-icon" aria-hidden="true" focusable="false" role="img">
      <use th:href="${button.prefix}"></use>
    </svg>
    <span th:text="${button.label}">Label</span>
    <svg th:if="${button.postfix}" class="usa-icon" aria-hidden="true" focusable="false" role="img">
      <use th:href="${button.postfix}"></use>
    </svg>
  </a>
</th:block>

<th:block th:fragment="button(items)" th:each="button: ${items}">
  <button th:unless="${button.href}" class="usa-button" th:classappend="${button.modifier}" th:attr="type=${button.type},disabled=${button.disabled},aria-disabled=${button.ariaDisabled}">
    <svg th:if="${button.check}" class="usa-icon" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" role="img">
      <path d="M3.5 9.42857L0 13L8 22L22 3.5L18 0L7.5 14L3.5 9.42857Z" fill="inherit"/>
    </svg>
    <svg th:if="${button.cross}" class="usa-icon" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" role="img">
      <path d="M14.667 11.0009L22 3.66696L18.3335 0L11 7.33392L3.66696 0.00088L0 3.66696L7.33348 11L0 18.3339L3.6674 22L11.0004 14.667L18.3335 22L22 18.3339L14.667 11.0009Z" fill="inherit"/>
    </svg>
    <svg th:if="${button.prefix}" class="usa-icon" aria-hidden="true" focusable="false" role="img">
      <use th:href="${button.prefix}"></use>
    </svg>
    <span th:text="${button.label}">Label</span>
    <svg th:if="${button.postfix}" class="usa-icon" aria-hidden="true" focusable="false" role="img">
      <use th:href="${button.postfix}"></use>
    </svg>
  </button>
  <a th:if="${button.href}" th:href="${button.href}" class="usa-button" th:classappend="${button.modifier}" th:attr="role=${button.role},disabled=${button.disabled},aria-disabled=${button.ariaDisabled},target=${button.target},rel=${button.rel}">
    <svg th:if="${button.check}" class="usa-icon" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" role="img">
      <path d="M3.5 9.42857L0 13L8 22L22 3.5L18 0L7.5 14L3.5 9.42857Z" fill="inherit"/>
    </svg>
    <svg th:if="${button.cross}" class="usa-icon" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" role="img">
      <path d="M14.667 11.0009L22 3.66696L18.3335 0L11 7.33392L3.66696 0.00088L0 3.66696L7.33348 11L0 18.3339L3.6674 22L11.0004 14.667L18.3335 22L22 18.3339L14.667 11.0009Z" fill="inherit"/>
    </svg>
    <svg th:if="${button.prefix}" class="usa-icon" aria-hidden="true" focusable="false" role="img">
      <use th:href="${button.prefix}"></use>
    </svg>
    <span th:text="${button.label}">Label</span>
    <svg th:if="${button.postfix}" class="usa-icon" aria-hidden="true" focusable="false" role="img">
      <use th:href="${button.postfix}"></use>
    </svg>
  </a>
</th:block>

Template fragment inclusion

Below is an example of how to use the fragment from the package directory using the th:block th:replace inclusion tag. Replace the fragment parameters using your variables or context.

<th:block th:replace="~{packages/cfa-button/cfa-button.th :: button(${items})}" />

ERB template partial

This is the pre-rendered partial template from the package. You may copy and paste from this example or use the template directly from the path.

<% items.each do |button| %>
  <% if button['href'] %>
    <a href="<%= button['href'] %>" class="usa-button<% if button['modifier'] %> <%= button['modifier'] %><% end %>"
      <% if button['ariaDisabled'] %> aria-disabled="<%= button['ariaDisabled'] %>"<% end %>
      <% if button['target'] %> target="<%= button['target'] %>"<% end %>
      <% if button['rel'] %> rel="<%= button['rel'] %>"<% end %>>
      <% if button['check'] %><svg class="usa-icon" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" role="img">
        <path d="M3.5 9.42857L0 13L8 22L22 3.5L18 0L7.5 14L3.5 9.42857Z" fill="inherit"/>
      </svg><% end %>
      <% if button['cross'] %><svg class="usa-icon" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" role="img">
        <path d="M14.667 11.0009L22 3.66696L18.3335 0L11 7.33392L3.66696 0.00088L0 3.66696L7.33348 11L0 18.3339L3.6674 22L11.0004 14.667L18.3335 22L22 18.3339L14.667 11.0009Z" fill="inherit"/>
      </svg><% end %>
      <% if button['prefix'] %><svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
        <use href="<%= button['prefix'] %>"></use>
      </svg>
      <% end %><span><%= button['label'] %></span><% if button['postfix'] %>
      <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
        <use href="<%= button['postfix'] %>"></use>
      </svg>
      <% end %>
    </a>
  <% else %>
    <button class="usa-button<% if button['modifier'] %> <%= button['modifier'] %><% end %>"
      <% if button['type'] %> type="<%= button['type'] %>"<% end %>
      <% if button['disabled'] %> disabled="<%= button['disabled'] %>"<% end %>
      <% if button['ariaDisabled'] %> aria-disabled="<%= button['ariaDisabled'] %>"<% end %>>
      <% if button['check'] %><svg class="usa-icon" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" role="img">
        <path d="M3.5 9.42857L0 13L8 22L22 3.5L18 0L7.5 14L3.5 9.42857Z" fill="inherit"/>
      </svg><% end %>
      <% if button['cross'] %><svg class="usa-icon" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" role="img">
        <path d="M14.667 11.0009L22 3.66696L18.3335 0L11 7.33392L3.66696 0.00088L0 3.66696L7.33348 11L0 18.3339L3.6674 22L11.0004 14.667L18.3335 22L22 18.3339L14.667 11.0009Z" fill="inherit"/>
      </svg><% end %>
      <% if button['prefix'] %><svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
        <use href="<%= button['prefix'] %>"></use>
      </svg>
      <% end %><span><%= button['label'] %></span><% if button['postfix'] %>
      <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
        <use href="<%= button['postfix'] %>"></use>
      </svg>
      <% end %>
    </button>
  <% end %>
<% end %>

<% items.each do |button| %>
  <% if button['href'] %>
    <a href="<%= button['href'] %>" class="usa-button<% if button['modifier'] %> <%= button['modifier'] %><% end %>"
      <% if button['ariaDisabled'] %> aria-disabled="<%= button['ariaDisabled'] %>"<% end %>
      <% if button['target'] %> target="<%= button['target'] %>"<% end %>
      <% if button['rel'] %> rel="<%= button['rel'] %>"<% end %>>
      <% if button['check'] %><svg class="usa-icon" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" role="img">
        <path d="M3.5 9.42857L0 13L8 22L22 3.5L18 0L7.5 14L3.5 9.42857Z" fill="inherit"/>
      </svg><% end %>
      <% if button['cross'] %><svg class="usa-icon" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" role="img">
        <path d="M14.667 11.0009L22 3.66696L18.3335 0L11 7.33392L3.66696 0.00088L0 3.66696L7.33348 11L0 18.3339L3.6674 22L11.0004 14.667L18.3335 22L22 18.3339L14.667 11.0009Z" fill="inherit"/>
      </svg><% end %>
      <% if button['prefix'] %><svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
        <use href="<%= button['prefix'] %>"></use>
      </svg>
      <% end %><span><%= button['label'] %></span><% if button['postfix'] %>
      <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
        <use href="<%= button['postfix'] %>"></use>
      </svg>
      <% end %>
    </a>
  <% else %>
    <button class="usa-button<% if button['modifier'] %> <%= button['modifier'] %><% end %>"
      <% if button['type'] %> type="<%= button['type'] %>"<% end %>
      <% if button['disabled'] %> disabled="<%= button['disabled'] %>"<% end %>
      <% if button['ariaDisabled'] %> aria-disabled="<%= button['ariaDisabled'] %>"<% end %>>
      <% if button['check'] %><svg class="usa-icon" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" role="img">
        <path d="M3.5 9.42857L0 13L8 22L22 3.5L18 0L7.5 14L3.5 9.42857Z" fill="inherit"/>
      </svg><% end %>
      <% if button['cross'] %><svg class="usa-icon" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" role="img">
        <path d="M14.667 11.0009L22 3.66696L18.3335 0L11 7.33392L3.66696 0.00088L0 3.66696L7.33348 11L0 18.3339L3.6674 22L11.0004 14.667L18.3335 22L22 18.3339L14.667 11.0009Z" fill="inherit"/>
      </svg><% end %>
      <% if button['prefix'] %><svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
        <use href="<%= button['prefix'] %>"></use>
      </svg>
      <% end %><span><%= button['label'] %></span><% if button['postfix'] %>
      <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
        <use href="<%= button['postfix'] %>"></use>
      </svg>
      <% end %>
    </button>
  <% end %>
<% end %>

Partial render

Below is an example of how to include the partial in a view from the package directory using the Ruby ERB class. Replace the argument values using your variables or context. In a Rails environment, the render method can be used instead with the same hash values.

<%= ERB.new(File.read('packages/cfa-button/_cfa-button.html.erb'), 0, 0, '@button').result_with_hash({items: items}) %>

Have a suggestion or need help?