Home Foundations Components Layout Tools Helpers
Search

Button

Buttons are used to perform actions within a page or view.

React Component

Variants

Primary

Default button styles, used with affirmative actions such as submitting, continuing, and saving.

Accent

Accent button styles, used for tertiary actions or when more contrast is needed.

Danger / Destructive

Danger or destructive button styles, used with actions that delete information such as deleting an item or removing a contact.

Secondary

Secondary button styles, used with neutral actions such as going back, saving as a draft, and canceling.

Subtle

Deprecated

Subtle buttons are deprecated. Replace Subtle button with a “plain” link. See documentation for the Link component.

Disclosure Button

The disclosure button is used with menus and dropdown components.

Month Add item

Loading State

Displays a loading indicator in the button, such as when a button is used to submit a form. Including the spinner_on_submit property will activate the loading state, and place the corresponding text as the aria-label.

Select to activate loading state

Small Button

Deprecated

With the Subtle button being deprecated, this property will be as well. Replace Subtle button with a “plain” link. See documentation for the Link component.

Full Width

Displays a button that takes up 100% of the width of its container. Enable the full_width treatment by adding the attribute: full_width: true.

Button Groups

Aligned to the end

Space Between

Left inline

Link

Nested button group

Link

Aligned to the end and border top

Button Group Wrap

When enabled, button groups are no longer restricted to a single row, allowing contents to wrap to multiple lines via flex-wrap: wrap.

Note: all button groups regardless of this attribute will wrap at breakpoints below sm-min to prevent horizontal scrolling on small screen devices.

Click the button below to toggle button group wrapping throughout the page, and resize your browser to view the resulting change.

Sage Component

SageButton 
<h2>Variants</h2>

<h3>Primary</h3>
<p>Default button styles, used with affirmative actions such as submitting, continuing, and saving.</p>

<%= sage_component SageButtonGroup, { gap: :sm, spacer: { bottom: :sm }} do %>

  <%= sage_component SageButton, {
    value: "Button",
    style: "primary",
  } %>

  <%= sage_component SageButton, {
    value: "Disabled",
    style: "primary",
    attributes: {
      type: "submit"
    },
    disabled: true,
  } %>

  <%= sage_component SageButton, {
    value: "Right icon",
    style: "primary",
    icon: {
      style: "right",
      name: "menu"
    }
  } %>

  <%= sage_component SageButton, {
    value: "Left icon",
    style: "primary",
    icon: {
      style: "left",
      name: "menu"
    }
  } %>

  <%= sage_component SageButton, {
    value: "Icon button",
    style: "primary",
    icon: {
      style: "only",
      name: "menu"
    }
  } %>
<% end %>

<%= sage_component SageDivider, {} %>

<h3>Accent</h3>
<p>Accent button styles, used for tertiary actions or when more contrast is needed.</p>

<%= sage_component SageButtonGroup, { gap: :sm, spacer: { bottom: :sm }} do %>

  <%= sage_component SageButton, {
    value: "Button",
    style: "accent",
  } %>

  <%= sage_component SageButton, {
    value: "Disabled",
    style: "accent",
    disabled: true,
    attributes: {
      type: "submit"
    }
  } %>

  <%= sage_component SageButton, {
    value: "Left icon",
    style: "accent",
    icon: {
      style: "left",
      name: "menu"
    }
  } %>

  <%= sage_component SageButton, {
    value: "Left icon",
    style: "accent",
    icon: {
      style: "left",
      name: "menu"
    }
  } %>

  <%= sage_component SageButton, {
    value: "Icon button",
    style: "accent",
    icon: {
      style: "only",
      name: "menu"
    }
  } %>
<% end %>

<%= sage_component SageDivider, {} %>

<h3>Danger / Destructive</h3>
<p>Danger or destructive button styles, used with actions that delete information such as deleting an item or removing a contact.</p>
<%= sage_component SageButtonGroup, { gap: :sm, spacer: { bottom: :sm }} do %>

  <%= sage_component SageButton, {
    value: "Button",
    style: "danger",
  } %>

  <%= sage_component SageButton, {
    value: "Disabled",
    style: "danger",
    disabled: true,
    attributes: {
      type: "submit"
    }
  } %>

  <%= sage_component SageButton, {
    value: "Left icon",
    style: "danger",
    icon: {
      style: "left",
      name: "menu"
    }
  } %>

  <%= sage_component SageButton, {
    value: "Left icon",
    style: "danger",
    icon: {
      style: "left",
      name: "menu"
    }
  } %>

  <%= sage_component SageButton, {
    value: "Icon button",
    style: "danger",
    icon: {
      style: "only",
      name: "menu"
    }
  } %>
<% end %>

<%= sage_component SageDivider, {} %>

<h3>Secondary</h3>
<p>Secondary button styles, used with neutral actions such as going back, saving as a draft, and canceling.</p>

<%= sage_component SageButtonGroup, { gap: :sm, spacer: { bottom: :sm }} do %>

  <%= sage_component SageButton, {
    value: "Button",
    style: "secondary",
  } %>

  <%= sage_component SageButton, {
    value: "Disabled",
    style: "secondary",
    disabled: true,
    attributes: {
      type: "submit"
    }
  } %>

  <%= sage_component SageButton, {
    value: "Right icon",
    style: "secondary",
    icon: {
      style: "right",
      name: "menu"
    }
  } %>

  <%= sage_component SageButton, {
    value: "Left icon",
    style: "secondary",
    icon: {
      style: "left",
      name: "menu"
    }
  } %>

  <%= sage_component SageButton, {
    value: "Icon button",
    style: "secondary",
    icon: {
      style: "only",
      name: "menu"
    }
  } %>
<% end %>

<%= sage_component SageDivider, {} %>

<h3>Subtle</h3>

<p>
  <%= sage_component SageBadge, {
    color: "danger",
    value: "Deprecated",
  }%>
  <%= md('Subtle buttons are deprecated. Replace Subtle button with a “plain” link. See documentation for the <a href="link">Link</a> component.') %>
</p>

<%= sage_component SageButtonGroup, { gap: :sm, spacer: { bottom: :sm }} do %>

  <%= sage_component SageButton, {
    value: "Button",
    style: "primary",
    subtle: true,
  } %>

  <%= sage_component SageButton, {
    value: "Disabled",
    style: "primary",
    disabled: true,
    subtle: true,
    attributes: {
      type: "submit"
    }
  } %>

  <%= sage_component SageButton, {
    value: "Right icon",
    style: "primary",
    subtle: true,
    icon: {
      style: "right",
      name: "menu"
    }
  } %>

  <%= sage_component SageButton, {
    value: "Left icon",
    style: "primary",
    subtle: true,
    icon: {
      style: "left",
      name: "menu"
    }
  } %>

  <%= sage_component SageButton, {
    value: "Icon button",
    style: "primary",
    subtle: true,
    icon: {
      style: "only",
      name: "menu"
    }
  } %>
<% end %>

<%= sage_component SageDivider, {} %>

<h3>Disclosure Button</h3>
<p>The disclosure button is used with menus and dropdown components. </p>

<%= sage_component SageButtonGroup, { gap: :sm, spacer: { bottom: :sm }} do %>
  <%= sage_component SageButton, {
    value: "Month",
    disclosure: true,
    attributes: {
      href: "#",
      rel: "noopener",
      title: "Select month"
    },
    style: "secondary",
  } %>

  <%= sage_component SageButton, {
    value: "Add item",
    disclosure: true,
    icon: { name: "add", style: "left" },
    attributes: {
      href: "#",
      rel: "noopener",
      title: "Add an item"
    },
    style: "secondary",
  } %>

  <%= sage_component SageButton, {
    css_classes: "sage-btn--rich-text",
    value: "Add item",
    icon: { name: "add", style: "only" },
    attributes: {
      href: "#",
      rel: "noopener",
      title: "Open Sassdocs site"
    },
    style: "secondary",
  } %>
<% end %>

<%= sage_component SageDivider, {} %>

<h3>Loading State</h3>
<p>Displays a loading indicator in the button, such as when a button is used to submit a form. Including the <code>spinner_on_submit</code> property will activate the loading state, and place the corresponding text as the <code>aria-label</code>.</p>

<%= sage_component SageButton, {
  value: "Select to activate loading state",
  spinner_on_submit: "my aria label",
  attributes: {
    href: "#",
    rel: "noopener",
    title: "Activate loading state"
  },
  style: "primary",
} %>

<%= sage_component SageDivider, {} %>

<h3>Small Button</h3>
<p> 
  <%= sage_component SageBadge, {
    color: "danger",
    value: "Deprecated",
  }%> 
  <%= md('With the Subtle button being deprecated, this property will be as well. Replace Subtle button with a “plain” link. See documentation for the <a href="link">Link</a> component.') %>
</p>

  <%= sage_component SageButton, {
    value: "Small button here",
    style: "primary",
    subtle: true,
    small: true
  } %>

<%= sage_component SageDivider, {} %>

<h3>Full Width</h3>
<p>Displays a button that takes up 100% of the width of its container. Enable the <code>full_width</code> treatment by adding the attribute: <code>full_width: true</code>.</p>
<div>
  <%= sage_component SageButton, {
    value: "Full width button example",
    style: "primary",
    full_width: true
  } %>
</div>

<%= sage_component SageDivider, {} %>

<h2>Button Groups</h2>

<%= sage_component SageDivider, {} %>

<h3>Aligned to the end</h3>

<%= sage_component SageButtonGroup, { gap: :sm, align: "end" } do %>
  <%= sage_component SageButton, {
    value: "Button",
    style: "secondary",
  } %>
  <%= sage_component SageButton, {
    value: "Button",
    style: "primary",
  } %>
<% end %>

<%= sage_component SageDivider, {} %>

<h3>Space Between</h3>

<%= sage_component SageButtonGroup, { gap: :sm, align: "space-between" } do %>
  <%= sage_component SageButton, {
    value: "Button",
    style: "secondary",
  } %>
  <%= sage_component SageButton, {
    value: "Button",
    style: "primary",
  } %>
<% end %>

<%= sage_component SageDivider, {} %>

<h3>Left inline</h3>

<%= sage_component SageButtonGroup, { gap: :sm } do %>
  <%= sage_component SageButton, {
    value: "Button",
    style: "primary",
  } %>

  <%= sage_component SageLink, {
    url: "#",
    label: "Link",
    external: false,
    launch: false,
    help_link: false,
    remove_underline: true,
    show_label: true,
    style: "secondary"
  } %>
<% end %>

<%= sage_component SageDivider, {} %>

<h3>Nested button group</h3>

<%= sage_component SageButtonGroup, { gap: :sm, align: "space-between" } do %>
  <%= sage_component SageLink, {
    url: "#",
    label: "Link",
    external: false,
    launch: false,
    help_link: false,
    remove_underline: true,
    show_label: true,
    style: "secondary"
  } %>

  <%= sage_component SageButtonGroup, { gap: :sm } do %>
    <%= sage_component SageButton, {
      value: "Button",
      style: "secondary",
    } %>

    <%= sage_component SageButton, {
      value: "Button",
      style: "primary",
    } %>
  <% end %>
<% end %>

<%= sage_component SageDivider, {} %>

<h3>Aligned to the end and border top</h3>

<%= sage_component SageButtonGroup, { gap: :sm, align: "end", borderTop: true } do %>
  <%= sage_component SageButton, {
    value: "Button",
    style: "secondary",
  } %>

  <%= sage_component SageButton, {
    value: "Button",
    style: "primary",
  } %>
<% end %>

<%= sage_component SageDivider, {} %>

<h3>Button Group Wrap</h3>
<p>When enabled, button groups are no longer restricted to a single row, allowing contents to wrap to multiple lines via <code>flex-wrap: wrap</code>.</p> 
<p>Note: all button groups regardless of this attribute will wrap at breakpoints below <code>sm-min</code> to prevent horizontal scrolling on small screen devices.</p>
<p>Click the button below to toggle button group wrapping throughout the page, and resize your browser to view the resulting change.</p>

<%= sage_component SageButton, {
  value: "Toggle button group wrap",
  style: "primary",
  icon: {
    style: "right",
    name: "menu-bordered"
  },
  attributes: {
    id: "button-group-wrap-example"
  }
} %>
Property Description Type Default

align

Aligns a button to the "right" rather than its default position.

["space-between" | "end"]

nil

attributes

Allows for the configuration of additional settings not previously described. It requires a Ruby hash, which is a collection of key-value pairs. Inside this hash, you can include valid properties such as data attributes.

Hash

nil

custom_content_class

Allows you to apply a custom CSS class when you provide custom HTML content within it. The primary purpose of using this custom CSS class should be to manage the layout of the custom content within the component.

String

nil

disabled

Toggles whether or not the button is disabled. On button this implements the "disabled" HTML attribute but on hyperlinks it enables the aria-disabled="true".

Boolean

false

disclosure

Toggles whether or not the button is a disclosure button. Disclosure buttons are intended to be used with menus and dropdowns.

Boolean

false

spinner_on_submit

When the button is in a loading state, this text will be set as the aria-label.

String

nil

full_width

Forces a button to 100% the width of its container.

Boolean

false

icon

Allows for configurations for an icon and its placement to be provided.

 
icon: {
  name: String,
  style: ["left" | "right" | "only"],
}

nil

icon_only

Determines whether a button has an icon with hidden text and applies the appropriate styling.

Boolean

false

raised

deprecated

Toggles "raised" shadows effect on standard buttons.

Boolean

false

small

deprecated

Toggles whether buttons in the "subtle" format can be display in a regular (default) and small size using this property.

Boolean

false

style

Buttons have several different "styles" that affect color appearance to create a "primary", "accent", "secondary", and "danger" variation.

["primary" | "accent" | "secondary" | "danger"]

primary

subtle

deprecated

Whether or not to render the button in the "subtle" format.

Boolean

false

value

The value to show on the button. If the "only" style is set for "icon", this label is visually hidden.

String

nil

Button Group

align

Adjusts the alignment of the buttons within.

["center" | "end" | "space-between"]

nil

borderTop

Adds a border-top to the component.

Boolean

false

gap

Adjusts the size of the gap between buttons.

[:xs | :sm | :md | :lg]

nil

wrap

Applies at breakpoints > sm-min only. This overrides the default behavior of limiting button groups to a single horizontal row, allowing buttons to wrap to fit within containers.

Boolean

false
Do

  • Communicating an action that will occur. (e.g. saving a page).

  • Triggering or enabling an action, such as submitting requested information. (e.g. forms).

  • Progressing or regressing a user through a step in a flow. (e.g. modals)

Don't

  • Directing users to a new page or different part within the same page. Instead, use a Link.

  • When space is limited consider an icon only button.

Version 6.1.2 SASS Docs Storybook