button docs

2.20.0

Bolt Button

Button Component in Bolt

Published

History
View changes
Install
yarn add @bolt/components-button
Source code
View on Github
Dependencies

Bolt's Component Explorer is being upgraded. It'll return in a future release!

Overview

Button is a branded component to convey call to action. Part of the Bolt “Components” CSS framework that powers the Bolt Design System.

Install via NPM
npm install @bolt/components-button

Description

Buttons are the core of our action components. Their affordance is immediate and can be use for most actions and allow users to access the target with a single interaction. Buttons clearly provide a next step for the user.

Our Buttons depend on the theme they are contained in and change in appearance based on said theme. The themes and button colors were designed together to ensure the proper amount affordance and clarity.

Xlight and light themes

  • Primary: Light Indigo container with white text
  • Secondary: white button with indigo text
  • Text button: Light indigo text with chevron

Dark and xdark themes

  • Primary: Yellow container with default indigo text
  • Secondary: white button with indigo text

  • Text button: white text with chevron

  • Currently only have one defined size (though other options can and will be defined in the future)

  • Can be 100% width of the wrapper for mobile or card instances
  • Can optionally be 100% width. For example, the button has default width of 2 rem on either side on larger screens but full width on smaller screens

Dos

  • CTAs must be clearly and succinctly labeled with a next step
  • CTA should lead with strong action verbs
  • The primary CTA should be the most important action.
  • Be consistent in placement based on the screen size and device
  • Fall back to the text button in secondary and tertiary content areas where you can. For example, cards with a button use the text style so that a filled button doesn't become overwhelming and redundant.
  • Follow theming rules

Don'ts

  • Don't clutter the page with too many buttons
  • Don't mix and match themes and their button colors. For example, do not use the indigo button on dark and xdark themes as the indigo button does not stand out enough.
  • Don't mix and match colors outside the theme, see button groups.

Usage

  {% include "@bolt-components-button/button.twig" with {
  text: "This is a button"
} only %}

Schema

Note: when assigning component props as HTML attributes on a web component, make sure to use kebab-case.

Prop Name Description Type Default Value Option(s)
attributes

A Drupal-style attributes object with extra attributes to append to this component.

 object —
  • —
text *

Text inside the button.

 string —
  • —
transform

Transforms the button text to various cases.

 string none
  • uppercase, lowercase, capitalize, none
type

Determines the button tag type for semantic buttons

 string —
  • button, submit, reset
size

Size of the button.

 string medium
  • xsmall, small, medium, large, xlarge
style

Style of the button determined by information hierarchy.

 string primary
  • primary, secondary, tertiary, text
width

Controls the width of the button.

 string auto
  • auto, full, full@small
border_radius

Rounds the corners of the button.

 string regular
  • regular or full
align

Horizontal alignment of items (text and icon) inside the button. Note: the values left and right are deprecated, use start and end instead.

 string center
  • start, center, end
icon

Icon data as expected by the icon component. Accepts an additional position prop that determines placement within the button.

 object —
    • position

      Where to position the icon within the button

      • before or after
    • attributes

      A Drupal-style attributes object with extra attributes to append to this component.

      • —
    • name

      Icon name

      • —
    • background

      Customizes the background that's displayed behind the SVG icon itself. Choosing any option other than none will automatically add a bit of space around the SVG so the background has the necessary space. Note, this option is now available to icons of all sizes!

      • none, circle, square
    • size

      Icon size.

      • small, medium, large, xlarge
    • color

      Icon color palette. Picking an option other than auto will override the default colors based on the color theme is placed within.

      • auto, teal, blue, indigo, yellow, orange, gray, green, white, pink
iconOnly

Make the button to display only the icon and hide the text (which is still required). You are required to pass both text and icon data for this option to work.

 boolean false
  • —
itemAlignment

Use the align parameter instead.

 —
  • —
rounded

Use the border_radius parameter instead.

 —
  • —
tag

Switch to using the new type prop instead.

 string button
  • a, link, button, submit, reset

button

button size variations

Note: medium is the default size.

button style variations

Note: interactive states only appear when the user interacts with the button, they are not styles that are available for use.

Regular States

    •

Interactive States

    •

button theme variations

Buttons inside a xdark theme

Buttons inside a dark theme

Buttons inside a light theme

Buttons inside a xlight theme

button width variations

Note: full@small means that the button will go from auto width to full width when the browser goes below the small breakpoint.

button border radius variations

button align variations

Note: the align prop only works with full width buttons.

button transform variations

button type variations

button with text and icon

Note: when passing icons inside a button, it is required to define the icon's position, by default it is set to after, which means the icon will come after the text.

Icon position set to before

Icon position set to after

button icon only

Note: an icon-only button still is still required to have text, and that text is accessible through screen readers. It's just visually hidden.

Xsmall icon-only button

Small icon-only button

Medium icon-only button

Large icon-only button

Xlarge icon-only button

Full border radius (circle icon-only button)

Examples with different icons

button with 3rd party js

Add a js- target class for the button to perform something through javascript

button with web component

Web Component Usage Bolt Button is a web component, you can simply use <bolt-button> in the markup to make it render.
This is a button
<bolt-button url="https://pega.com"> This is a button </bolt-button>
Basic Usage To use icon in combination with text within the button, you must pass <bolt-icon> with a slot attribute defined as either before or after. Note: the slot attribute is required in order for the icon to be placed and spaced correctly within the button. Even if icon-only option is turned on, slot is still required.

This is a button

This is a button

This is a button

<p> <bolt-button> <bolt-icon name="chevron-left" slot="before"></bolt-icon> This is a button </bolt-button> </p> <p> <bolt-button> <bolt-icon name="chevron-right" slot="after"></bolt-icon> This is a button </bolt-button> </p> <p> <bolt-button icon-only> <bolt-icon name="close" slot="before"></bolt-icon> This is a button </bolt-button> </p>
Advanced Usage The web component has all the options shown in the schema table. You can define each prop within the <bolt-button> element. Use unique combinations to customize a button to your liking. Note: the style prop is named color instead.
This is a button
<bolt-button url="https://pega.com" size="large" color="secondary" border-radius="full" tag="a" icon-only > <bolt-icon name="menu" slot="before"></bolt-icon> This is a button </bolt-button>
Server-side Rendered Web Components (Experimental) The <bolt-button> component, among many other web components in Bolt, will support server-side rendering via the new upcoming {% filter bolt_ssr %} custom Twig filter. Check out the docs on server-side rendering for information!
This is a button
<bolt-button> This is a button <bolt-icon name="chevron-right" slot="after"></bolt-icon> </bolt-button>
Debug Panel