Buttons

Primary and Secondary Examples

Sizes

Most Buttons are available in four sizes: extra small, small, medium and large.

When to Use

• The default button size (medium) will be used in most cases, but there may be a need for smaller or larger buttons. For example, an extra small button may be needed to fit into a table, while a large button may appear on a hero banner or marketing scenario.

Examples

Usage

Button Labels

Buttons labels should always be clear. To ensure clarity, use all caps for button labels. Always use clear, concise wording. See Voice and Tone for additional guidance. It is best to use action-oriented words that accurately set users’ expectations.

Placement and Positioning

Primary calls to action appear in the bottom right on desktop/tablet. On mobile, they may appear on the bottom right or they may span the full width. If there are multiple buttons on a mobile screen, the primary action should appear in the top-most position.

Secondary actions appear to the left of the primary action on desktop. On mobile, they may appear to the left or below the primary action. In addition, irreversible functions (“Cancel”) should appear on the far left, while non-destructive functions (“Save”) should appear next to the primary action.

Examples

Brand Button

Primary Action Button

When to Use

• Use a primary action button to indicate the desired or next likely action the user will take. Limit use to a single button on a screen or within a panel.

Secondary Button

When to Use

• Use a secondary button for non-primary actions.

Negative Button

Multi-Action Button

When selected, a Multi-Action Button displays a menu of closely-related actions that the user can take. Multi-Action Buttons are available in extra small to medium-sized buttons.

Combo Button

The Combo Button provides a primary action along with a menu of related secondary actions. Combo Buttons are available in extra small to medium-sized buttons.

Text-Only Button

The text-only button style is a button without a border or a background that inherits the primary action color.

Additional Guidelines

If there are multiple text-only buttons, there should be plenty of space to separate them. These buttons contain padding, and in some instances it may make more sense to use an <a> tag instead.

Icon Button

A button can also be used as an icon without text. An icon-only button should always have a tooltip hint with the action of the button.

When to Use

• Use icon-only buttons when space is at a premium.
• Use icon-only buttons when the icon is clear and self-explanatory such as an “x” icon to denote a close action.

Progress Button

When selected, a Progress Button displays a small Progress Indicator within the button, providing feedback when a process requires any wait time before an action is complete. Upon successful completion, the Progress Button displays a confirmation check icon. If an action is unsuccessful, the Progress Button should return to its initial state without displaying a confirmation.

Progress Buttons are available in all button types and sizes, except for the Text-Only Button.

When to Use

• Use a Progress Button to provide quick feedback when the user takes action.
• Progress Buttons should be used for asynchronous actions.

Additional Guidelines

• Disable any form inputs associated with the Progress Button, once selected, to prevent changes while the user waits.
• With unsuccessful actions, provide follow-up feedback by displaying a Page-Level or Container-Level Message rather than a Toast Message, since important information explaining the situation needs to persist on the screen.

Additional Guidelines

Do not mix sizes of buttons that are located next to one another. If differentiation is needed, utilize the primary, secondary and text button styles.

Do not use the full-width style for large sections.

Developer Notes

Brand Button

<button class="spark-btn spark-btn--lg spark-btn--brand">Default</button>

<style type="text/css">
  
</style>

Add a class of spark-btn--brand and spark-btn--lg to create a large, branded button.

Default Button

<button class="spark-btn spark-btn--md">Default</button>

<style type="text/css">
  
</style>

The styling of a primary button will be present on any button that has a class of spark-btn and no additional classes like spark-btn--secondary.

Sizes

<div class="spark-mar-b-2 spark-btn-group spark-btn-group--left">
  <button class="spark-btn spark-btn--lg spark-btn-group-primary">Large</button>
  <button class="spark-btn spark-btn--lg spark-btn--secondary spark-btn-group-secondary">Large</button>
</div>
<div class="spark-mar-b-2 spark-btn-group spark-btn-group--left">
  <button class="spark-btn spark-btn--md spark-btn-group-primary">Medium</button>
  <button class="spark-btn spark-btn--md spark-btn--secondary spark-btn-group-secondary">Medium</button>
</div>
<div class="spark-mar-b-2 spark-btn-group spark-btn-group--left">
  <button class="spark-btn spark-btn--sm spark-btn-group-primary">Small</button>
  <button class="spark-btn spark-btn--sm spark-btn--secondary spark-btn-group-secondary">Small</button>
</div>
<div class="spark-btn-group spark-btn-group--left">
  <button class="spark-btn spark-btn--xs spark-btn-group-primary">Extra Small</button>
  <button class="spark-btn spark-btn--xs spark-btn--secondary spark-btn-group-secondary">Extra Small</button>
</div>

<style type="text/css">
  
</style>

To render a large, medium, small or extra small button, apply a class of spark-btn--lg, spark-btn--md, spark-btn--sm or spark-btn--xs respectively.

Secondary Button

<button class="spark-btn spark-btn--md spark-btn--secondary">Secondary</button>

<style type="text/css">
  
</style>

Add the spark-btn--secondary class to a button to mark it as a secondary action within a section of the application.

Negative Button

<button class="spark-btn spark-btn--sm spark-btn--negative">Negative</button>

<style type="text/css">
  
</style>

Multi-Action Button

<div class="spark-popover">
  <button id="example-menu-button-1" class="spark-btn spark-btn--md spark-btn--multi-action spark-popover__toggle" aria-haspopup="true" aria-controls="example-popover-1" aria-expanded="false">
    <span>Create New</span>
  </button>

  <div id="example-popover-1" class="spark-popover__content" role="tooltip" data-anchor-x="center" data-anchor-y="bottom">
    <ul class="spark-popover__list" role="menu" aria-labelledby="example-menu-button-1">
      <li class="spark-popover__list-item" role="none">
        <a tabindex="0" class="spark-popover__list-link" role="menuitem">Reservation</a>
      </li>
      <li class="spark-popover__list-item" role="none">
        <a tabindex="0" class="spark-popover__list-link" role="menuitem">Customer Profile</a>
      </li>
      <li class="spark-popover__list-item" role="none">
        <a tabindex="0" class="spark-popover__list-link" role="menuitem">Housekeeping Request</a>
      </li>
    </ul>
    <span class="spark-popover__caret"></span>
  </div>
</div>


<style type="text/css">
  
</style>

A Multi-Action Button utilizes the Popover component to display a menu of actions that a user can take on a particular screen. To display a Multi-Action Button, use the spark-btn--multi-action class in conjunction with the spark-btn class and one of spark-btn--md, spark-btn--sm or spark-btn--xs classes for sizing. A class of spark-popover__toggle is also required on the button or link element to allow toggling the Popover’s visibility. For the proper amount of spacing within the button, a span element should be used to contain the label of the button.

The menu items within the Popover will either be links pointing to another page or actions that are to be performed on the same page. In the second scenario, a custom event listener will be required to perform the desired action when a user clicks one of the menu items. As part of performing that action, the Popover’s close() method can be utilized to close the Popover once the action has been started or is complete. For more details, refer to the API documentation for the Popover component.

Combo Button

<div class="spark-btn-combo">
  <button class="spark-btn spark-btn--md spark-btn-combo__primary">Save</button>

  <div class="spark-popover">
    <button id="example-menu-button-1" class="spark-btn spark-btn--md spark-btn-combo__secondary spark-popover__toggle" aria-label="Save Menu" aria-haspopup="true" aria-controls="example-popover-1" aria-expanded="false"></button>

    <div id="example-popover-1" class="spark-popover__content" role="tooltip" data-anchor-x="left" data-anchor-y="bottom">
      <ul class="spark-popover__list" role="menu" aria-labelledby="example-menu-button-1">
        <li class="spark-popover__list-item" role="none">
          <a tabindex="0" class="spark-popover__list-link" role="menuitem">Reservation</a>
        </li>
        <li class="spark-popover__list-item" role="none">
          <a tabindex="0" class="spark-popover__list-link" role="menuitem">Customer Profile</a>
        </li>
        <li class="spark-popover__list-item" role="none">
          <a tabindex="0" class="spark-popover__list-link" role="menuitem">Housekeeping Request</a>
        </li>
      </ul>
      <span class="spark-popover__caret"></span>
    </div>
  </div>
</div>


<style type="text/css">
  
</style>

A Combo Button is a combination of two buttons placed side-by-side, with a spark-btn-combo container element used to create and hold the Combo Button. The Combo Button’s primary action is a button with a class of spark-btn-combo__primary and is an immediate child element of the container element. The secondary action is a button with a class of spark-btn-combo__secondary and as it also utilizes the Popover component, has a spark-popover__toggle class to toggle the visibility of the menu of related actions.

As the Combo Button is similar to the Multi-Action Button, refer to the Multi-Action Button documentation above on how to handle clicking of menu items within the Popover.

Icon Button

<button class="spark-btn--icon spark-icon spark-icon-cog spark-tooltip tooltip-initialized" aria-label="Settings" aria-expanded="false" aria-describedby="tooltip1">
  <span id="tooltip1" class="spark-tooltip__content--left" role="tooltip" data-affixed="">
      Change your settings
      <span class="spark-tooltip__caret" data-position="left"></span>
  </span>
</button>

To display the filled version of the icon in the active state, a class of spark-icon--fill has to be added to the button. For pages loaded using ajax, custom logic might be required within the application to manage the toggling of active states for different buttons. Refer to the Tooltip documentation for Tooltip configuration options, including position.

Progress Button

A Progress Button is constructed with the spark-btn and spark-progress classes. Contained within the button is an indeterminate progress element, a confirmation icon and a label.

The component is instantiated using new Spark.Button(el). The following methods are available to control the states of the button.

For all available methods and full API, refer to the component code on Bitbucket.

<div class="container spark-pad-l-0 spark-pad-r-0">
  <div class="row">
    <div class="col-xs-12 spark-mar-b-2">
      <label class="spark-input">
        <input class="spark-input__field" name="example1" placeholder="Reservation Number" role="textbox" value="7SPRK5">
        <span class="spark-label">Find Reservation</span>
      </label>
    </div>

    <div class="col-xs-12">
      <button class="spark-btn spark-btn--md spark-progress spark-pull-right">
        <progress></progress>
        <span class="spark-progress__meter"></span>
        <i aria-hidden="true" class="spark-btn__icon spark-icon spark-icon-check spark-icon--fill" data-type="success"></i>
        <span class="spark-btn__label">Submit</span>
      </button>
    </div>
  </div>
</div>

<style type="text/css">
  
</style>

var button = document.querySelector('button.spark-progress');
var textInput = document.querySelector('.spark-input');

// create Spark Text Input
var sparkText = new Spark.TextInput(textInput);

// create Spark Progress Button
var sparkButton = new Spark.Button(button);

// add a listener handle to fake form submit
button.addEventListener('click', function() {
  if(sparkButton.getActive() === false){

    // set activity state to true
    sparkButton.setActive(true);

    // pretend the you have a 1 sec async call
    var fakeDelay =  setTimeout(function() {

      // fake activity completed successfully
      sparkButton.success();
    }, 1000);
  }
});

Progress Button with Error

<div class="container spark-pad-l-0 spark-pad-r-0">
  <div class="row">

    <div class="col-xs-12 spark-mar-b-2">
      <label class="spark-input">
        <input class="spark-input__field" name="example1" placeholder="Reservation Number" role="textbox" value="7SPRK5">
        <span class="spark-label">Find Reservation</span>
        <span class="spark-input__message"></span>
      </label>
    </div>

    <div class="col-xs-12">
      <button class="spark-btn spark-btn--md spark-progress spark-pull-right">
        <progress></progress>
        <span class="spark-progress__meter"></span>
        <i aria-hidden="true" class="spark-btn__icon spark-icon spark-icon-check spark-icon--fill" data-type="success"></i>
        <span class="spark-btn__label">Error</span>
      </button>
    </div>

  </div>
</div>

<style type="text/css">
  
</style>

var button = document.querySelector('button.spark-progress');
var textInput = document.querySelector('.spark-input');

// create Spark Text Input
var sparkText = new Spark.TextInput(textInput);

// create Spark Progress Button
var sparkButton = new Spark.Button(button);

// add a listener handle to fake a submit.
button.addEventListener('click', function() {
  if(sparkButton.getActive() === false){

    // pretend they changed it and resubmit
    sparkText.clearError();

    // set the spark button active state to true
    sparkButton.setActive(true);

    // pretend the you have a 1 sec async call
    var fakeDelay =  setTimeout(function() {

      // fake call came back with a fake error.
      sparkText.setError('Invalid Reservation Number.')

      // fake activity did not complete successfully
      sparkButton.fail();
    }, 1000);
  }
});

Anchor Tag

All button classes can safely be applied to <a> elements as well. In some instances a <button> may not make sense for functional reasons.

Disabled Button

<button class="spark-btn spark-btn--md" disabled>Disabled</button>

Adding the disabled attribute to the button element will style the button accordingly.

Accessibility Notes

Multi-Action Button

The Multi-Action Button requires additional ARIA attributes to make it fully accessible particularly when being used with assistive technologies. The spark-popover__toggle button used to toggle the visibility of the Popover requires an id attribute and three ARIA attributes: aria-haspopup, aria-controls, and aria-expanded.

• id - This attribute is used to provide a label for the menu included in the Popover.
• aria-haspopup - This attribute is used to indicate that the button has a popup context menu or sub-level menu. It is recommended for use only when a menu is to be revealed. The value of this attribute should be set to true.
• aria-controls - This attribute indicates which element is controlled by the menu button. The value of this attribute should be the id property of the element it controls.
• aria-expanded - This attribute indicates the current state of the Popover associated with the button. The possible values are true or false, and are managed by Javascript whenever the Popover is toggled.

<button id="example-menu-button-1" class="spark-btn spark-btn--xs spark-btn--multi-action spark-popover__toggle" aria-haspopup="true" aria-controls="example-popover-1" aria-expanded="false">
  <span>Create New</span>
</button>

Some elements within the Popover used with the Multi-Action button also require additional attributes set to ensure they are properly associated with the properties set on the button.

The following attributes are required for the spark-popover__content element:

• id - This attribute should be set on the spark-popover__content element as its value is used as the value of the aria-controls attribute above.
• role - The role of the spark-popover__content element should be set to tooltip.

The following attributes are required for the spark-popover__list element:

• role - The role of the spark-popover__list element should be set to menu.
• aria-labelledby - This attribute should be set on the spark-popover__list element with its value being the value of the Multi-Action id attribute.

The li elements within the spark-popover__list should have an attribute of role set to none. This is to hide the implied listitem role of the element from assistive technologies.

<div id="example-popover-1" class="spark-popover__content" role="tooltip" data-anchor-x="center" data-anchor-y="top">
  <ul class="spark-popover__list" role="menu" aria-labelledby="example-menu-button-1">
    <li class="spark-popover__list-item" role="none">
      <a tabindex="0" class="spark-popover__list-link" role="menuitem">Reservation</a>
    </li>
  </ul>
  <span class="spark-popover__caret"></span>
</div>

Combo Button

The spark-popover__toggle element and Popover content container used in the Combo Button should use the attributes and properties defined and discussed above in the Multi-Action Button accessibility guidelines.

Text-Only Button

The Text-Only Button has been designed to be fully accessible in terms of Color Contrast when used on a white background (#FFFFFF) or the light gray (#EEEEEE) typically used within Spark components. If you need to place the button on the darker gray background typically used for the page background (#E4E4E4), you will need to add custom CSS to update the default color of the button to #1F7261. This color is included in the SCSS color variables within Spark. The hover and focus states will remain the same and will not need to be customized.

If using a background color that is not one of the above, the Text-Only button may fail the contrast checker test and you will need to evaluate what changes are needed to ensure the Text-Only Button meets the Accessibility and Color Contrast standards defined and used within Spark.

Icon Buttons

For more information on how to make Icon Buttons accessible, refer to the Tooltips accessibility documentation.