Buttons Buttons signal an action for someone to take

Buttons are the most common way people using our applications conduct actions in our interfaces. Resonance has several variations of the button component, with the distinguishing factor between these variations being the relative importance of the action in context.

Table of contents


Usage guidelines

When to use
  • A Resonance button should be used wherever you would use a standalone native button element.
  • A Resonance button can contain either native button elements or links / anchor elements (<a>).
  • If the link's primary purpose is to let someone do something, it can be a Resonance button.
  • If the link's primary purpose is to let someone go somewhere, it should not be a Resonance button.
How to use
  • Use action-oriented language; because buttons are fundamentally about actions, the button should say what it does, not what it is. For instance, a button that opens an image cropping tool should say 'Crop', not 'Crop tool'.
  • Use sentence case for all buttons.
  • When placing multiple buttons together:
  • Try to group them horizontally where possible.
  • Position the more important actions to the left of / on top of other actions.
  • When pairing icons with text:
  • Make sure that the icon only supplements or clarifies the text, and that the text could work without the icon.
  • Put the icon to the left of the text.
  • It is sometimes acceptable to use an icon-only button.
  • Only do so when space is constrained and when the meaning of the icon is readily understood on its own by the average person using your app.
  • Keep in mind that not everyone using your app will be able to see the icon; consider using visually-hidden labels instead.
Content guidelines
  • Use concise, actionable language (e.g., Publish now, Download, Save).
  • Check the story editor and Chorus Video before establishing a new label or verb sequence. For example, sidebars use Close and Update instead of Done, Save, or Dismiss.

Variations

Default button

Default buttons are the least important actions that still require an actionable signal. A button being default suggests that the action is tertiary in importance to the workflow. The default button pattern is also useful for large groups of related actions of similar importance, such as in the editor's layout tool.

Secondary button

A secondary button is for optional or advanced functionality.

Secondary buttons can appear multiple times on the same screen, so long as the hierarchy makes sense for a given workflow.

Primary button

Use a primary button at most once in each view, for the strongest call-to-action. Clicking the primary button on a screen is usually the last thing someone will do on that screen.

Negative button

A negative button is reserved for destructive actions that delete data. It should be used sparingly and only when the action cannot be undone. To make one, add a negative attribute to a default button.



Attributes

An asterisk next to a value denotes that it is the default value for that attribute. Unless noted otherwise, attributes should be added to the component element directly. Boolean attributes work based on their presence or absence from the component.

<res-component booleanAttribute stringAttribute="parameter">    
  <child-element></child-element>
</res-component>
AttributeTypeDescription
designstringSet button type
  • default
  • primary
  • secondary
disabledbooleanSet initial disabled state
negativebooleanSet button to negative state (only on default design)
paddinglessbooleanRender button without padding (so that the res-button only takes up as much space as its content)
valuestringUsed to pass active value to res-toggle-buttons
activebooleanSet button to active inside a res-toggle-buttons

API

NameTypeDataDescription
designpropertybooleanGet/set button design
disabledpropertybooleanGet/set disabled state

Notes

Depends on:
Required DOM

Without these, the component will throw an error on render.

  • <button|input|a> - Button element
Supported optional DOM

If added as children, these elements will receive specific styles and/or functionality.

  • <res-icon> - Icon element

History

VersionNote
0.23.2Prevent determineIconState from giving buttons multiple states
0.21.4Package upgrades cause CSS build to remove -moz-appearance property
0.15.4Make res-buttons not titlecase by default, Remove border from paddingless default buttons' inner buttons, make icon-only buttons not underline on hover
0.15.0Add paddingless variant.
0.12.0Apply new spacing scale.
0.11.0Tweaks to accommodate new icon set
0.10.0Color update. Remove error styles for primary and secondary buttons, and change error to negative attribute.
0.7.0Web component refactor
0.5.0Total refactor! Component now can be passed button, input, or anchor tags. Icon position mirrors tag order. Changed type attribute to design.
0.4.0Error states, and button can now be links.
0.3.0Total rebuild to reflect most recent button designs.
0.1.0Initial build to spec.