Buttons

Invoke and communicate an action that will occur

# Overview

# Primary

Use primary buttons for actions to complete a task or to move forward in a process such as "Add to cart." There is only one primary action per major page section.

# Secondary

Use secondary buttons for all actions that do not move the user to the next step or require additional user actions such as "Add to wish list" or "Find a campout near you."

# Text and Icon

Pair an icon with text to improve recognition about an object or action.

# Icon Only

Use icons to visually communicate an object or action in a limited space. Include alternative text to describe what the button does.

# Icon Only With Background

Use with-background property in conjunction with the icon-only property to make icon buttons more identifiable. Include alternative text to describe what the button does.

# Full Width

Displays at full width of its container.

# Sizing

Change the button size based on where the button is used. The default size is medium. Small is used for supplemental user actions such as product comparison or filter. Large is used for "Add to cart" on product pages or for Call to Action.

# Accessibility

Many WCAG requierments are contextual to their implementation. To ensure that usage of this component complies with accessibility guidelines you are responsible for the following:

  • For icon-only buttons, provide aria-label text that describes the button's action
  • If activating the button does not dismiss the current context, then focus typically remains on the button after activation, e.g., an Apply or Recalculate button.
  • If a description of the button's function is present, the button element has aria-describedby set to the ID of the element containing the description.
  • If the button is a toggle button, it has an aria-pressed state. When the button is toggled on, the value of this state is true, and when toggled off, the state is false.
  • If the button action indicates a context change, such as move to next step in a wizard or add another search criteria, then it is often appropriate to move focus to the starting point for that action.
  • Apply keyboard interaction patterns as described on REI universal design and accessibility: Buttons

This component has no specific WCAG compliance attributes built into the control. It is possibile to define this component as a link or button:

  • Select the semantically-correct element, which will ensure that assistive technologies have correct instructions for how to interact with the component
  • Use the CdrLink component to make a button that looks like a link
  • Do not use div or input elements
  • Do not add role="button" to the CdrButton component

# Guidelines

# Use When

  • Triggering an action
  • Enabling a “final” action
  • Progressing or regressing a user through a step in a flow
  • Submitting requested information
  • Confirming the completion of a flow or cancelling out of it

# Don't Use When

  • Navigating to another page on a site. Instead use Call to Action
  • Taking users to a different part within the same page. Instead, use Links

# The Basics

Buttons sizes are used:

  • Small: Supplemental user actions such as product comparison or filter on product pages
  • Medium: Default size
  • Large: Mobile version for XS grid with full breakpoint width. Also, for "Add to cart" on product pages or for Call to Action on campaign pages

When stacking buttons vertically:

  • Align left borders
  • Display all with the same width
  • Separate each by stack-1-x spacing

When arranging buttons horizontally:

  • Align top borders
  • Display all with the same height
  • Separate each by standard inline-1-x spacing

# Do / Don't

When grouping buttons, match button sizes either horizontally or vertically.

Image showing proper vertical button grouping
Do match button widths.
Image showing mixed button sizing
Don't mix button sizes.

Image showing proper button height grouping
Do match button heights.
Image showing mixed button sizing
Don't mix button sizes.

# Content

  • Clearly and concisely label with 1–3 words and fewer than 20 characters, including spaces

  • Start with a verb, if possible. Labels must be action-oriented and set expectations for what the user will see next

  • Never repeat the context of a label when the context is already clear. For example, for a "Save" button, do not expand to "Save Account Information"

  • Use sentence case. Do not use all caps, title caps, or all lowercase

# Do / Don't

Image showing buttons with proper text length
Do minimize label length.
Image showing buttons with too much text
Don't put too much text in a button.
Image showing buttons with proper text sentence case
Do use sentence case.
Image showing buttons with title case
Don't use title case.
Image showing buttons with proper noun capitalization
Do capitalize any proper nouns.
Image showing buttons with all uppercase text
Don't use all caps.

# Behavior

When making decisions about whether to use a link or a button, consider the following:

Links Buttons
Answers the question, "Where can I go" Answers the question, "What can I do"
Search engine crawlers can follow anchors for links (<a>) Search engine crawlers cannot follow links that are submitted by input or button
Default keyboard behavior is triggered using the Enter key Default keyboard behavior is triggered using the Space or Enter key
Cannot be disabled like buttons but can be made inert with tabindex="-1" and aria-hidden="true" Can be disabled with disabled attribute

Apply the following use cases when deciding when to use links as anchors or buttons:

Links Buttons
Navigating user to a new page or view Toggling a display to full screen
Changing the URL Opening a modal window
Causing a browser redraw or refresh Triggering a popup menu
Supporting internal page jumps Can be disabled with disabled attribute

# Resources


# API

# Props

This component will bind any attribute that a native HTML button element accepts.

tag

name

string

type

'button'

default

Renders CdrButton as a <button> or <a> element. When using the value of <a>, this element renders as an anchor link. Possible values: { 'button' | 'a' }

type

name

string

type

'button'

default

Sets the button type. Possible values: { 'button' | 'submit' | 'reset' }

fullWidth

name

boolean

type

false

default

Sets button width to 100%. Setting this value to true will set the button width to 100% of the parent container. Use the 'fullWidth' prop with the 'size' prop to control top and bottom padding.

size

name

string

type

'medium'

default

Sets the button size; values can target responsive breakpoints. Breakpoint values are: xs, sm, md, and lg. Examples: { 'small' | 'medium' | 'large' | 'large@sm' }

iconOnly

name

boolean

type

false

default

Renders an 'icon-only' button. When this value is true, it will override the size and 'responsiveSize' props. Can be used in conjunction with 'with-background'

withBackground

name

boolean

type

false

default

Renders an 'icon-only' button with a background color and border. Must be used in conjunction with the 'iconOnly' prop.

modifier

name

string

type

N/A

default

Modifies the style variant for this component. Possible values: { 'secondary' }

# Slots

Find more information about using Slots in the article Getting Started as a Developer.

default

name

Sets the innerHTML for CdrButton'. This is the readable text of the button. Leave empty if icon-only.

icon

name

Sets the innerHTML for CdrButton. This is for the icon.

# Usage

# Size Prop

The below example uses the size prop to set a default and responsive size. This button’s size is small, but it will become a large button at the xs and sm breakpoints.



 





<template>
  <cdr-button
    size="small large@xs large@sm"
  >
    Add to cart
  </cdr-button>
</template>
1
2
3
4
5
6
7

# Modifiers

The following variants are available to the cdr-button modifier attribute:

Value Description
'secondary' Sets the secondary style for the button

# Click Actions

Use an @click event handler to attach custom actions and event handling.



 
















<template>
  <cdr-button
    @click="greet"
  >
    Greet
  </cdr-button>
</template>

<script>
export default {
  ...
  methods: {
    greet() {
      console.log(‘Hello there’);
    }
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# Composing with Icons

CdrButton component can be used with the icon component from the CdrIcon package.

# Text and Icon

To scale Cedar icons appropriately, include the cdr-button__icon class with any icon component. The size prop scales both the icon and the button.

In the below example, a "Download" button is rendered as a button with icon and text using and inline Cedar icon component.





 
















<template>
  <cdr-button>
    <IconDownload
      slot="icon"
      class="cdr-button__icon"
    />
    Download
  </cdr-button>
</template>

<script>
import { CdrButton, IconDownload } from '@rei/cedar';
export default {
  ...
  components: {
     CdrButton,
     IconDownload,  
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# Icon Only

Use the following props to modify cdr-button:

  • Default slot must be empty. If text is present in default slot, the text will render
  • size prop is disabled when icon-only prop is true
  • with-background can be used to add a border and background to the icon-only button, ensuring it is more visible on darker backgrounds
  • Add aria-label text to describe the button’s action when clicked or tapped


 
 
 








<template>
  <cdr-button
    :icon-only="true"
    :with-background="true"
    aria-label="Complete this step"
  >
    <icon-check-lg
      slot="icon"
      class="cdr-button__icon"
    />
  </cdr-button>
</template>
1
2
3
4
5
6
7
8
9
10
11
12