Button

A graphical element that indicates interactivity.

Published

Last updated: 5.0.0

Github

NPM

Twig Usage

{% include '@bolt-elements-button/button.twig' with {
  content: 'This is a button',
  attributes: {
    type: 'submit'
  }
} only %}

Schema

Prop Name	Description	Type	Default Value	Option(s)
attributes	A Drupal-style attributes object with extra attributes to append to this component.	`object`	—	—
content *	Content of the button.	`any`	—	—
icon_before	Append an icon before the button content. Icon element is recommended. However, <img> elements are also acceptable.	`any`	—	—
icon_after	Append an icon after the button content. Icon element is recommended. However, <img> elements are also acceptable.	`any`	—	—
icon_only	Append an icon to the button content and visually hide the text content. This prop trumps icon_before and icon_after.	`any`	—	—
hierarchy	Style the button appropriately based on information hierarchy.	`string`	`primary`	`primary`, `secondary`, `tertiary`, `transparent`
size	Control the font-size and padding of the button.	`string`	`medium`	`xsmall`, `small`, `medium`, `large`
border_radius	Control the border radius of the button.	`string`	`small`	`small`, `large`, `full`
display	Control the display of the button.	`string`	`inline`	`inline`, `block`, `inline@from-small`

Install

npm install @bolt/elements-button

Dependencies

@bolt/core-v3.x

Basic Button

A button is generally an inline interactive graphical element. Its main purpose is to help the user perform a function (sometimes navigate). <button class="e-bolt-button"> is acceptable at rendering a button, though the Twig template is the recommended usage for Drupal.

Important Notes:

Only text should be passed to the content prop. However, <span>, <em>, and <strong> elements can be used.

Button element is a replacement for the Button component.

Demo

Light

Dark

Twig

{% include '@bolt-elements-button/button.twig' with {
  content: 'This is a button',
  attributes: {
    type: 'button'
  }
} only %}

HTML

<button type="button" class="e-bolt-button">This is a button</button>

Button as an <a> element

When appropriate, an <a> element can use the button style. For example, the button helps to navigate to another page.

Important Notes:

If a button serves navigational purpose, the proper URL must be set with the href attribute.

Demo

This looks like a button but semantically is an anchor

Twig

{% include '@bolt-elements-button/button.twig' with {
  content: 'This looks like a button but semantically is an anchor',
  attributes: {
    href: 'https://google.com',
  }
} only %}

HTML

<a href="https://google.com" class="e-bolt-button">This looks like a button but semantically is an anchor</a>

HTML Attributes for Button

Depending on if the <a> element or the <button> element is being used, the proper HTML attributes should be passed.

Important Notes:

<a> requires the href attribute.

<button> requires the type attribute.

Demo

This button has the "href", "target", and "id" attributes

Twig

// <button>
{% include '@bolt-elements-button/button.twig' with {
  content: 'This button has the "type" attribute',
  attributes: {
    type: 'submit',
  }
} only %}

// <a>
{% include '@bolt-elements-button/button.twig' with {
  content: 'This button has the "href", "target", and "id" attributes',
  attributes: {
    href: 'https://google.com',
    target: '_blank',
    id: 'js-bolt-some-unique-id'
  }
} only %}

HTML

<a href="https://google.com" target="_blank" id="js-bolt-some-unique-id" class="e-bolt-button">This button has the "href", "target", and "id" attributes</a>

Button with Icon

Icons can be used in tandem with a button. An icon can be placed before and/or after the button text. The icon component is recommended for appending icons. However, an <img> element is also acceptable.

Important Notes:

Icons are set inline with text so icon size will grow or shrink with text size. The size and background props for the icon component are not well supported in this scenario.

When writing in plain HTML, all white space must be eliminated to have the icon display correctly next to text (in terms of spacing and wrapping). The markup must be written all in one line and spaces between HTML elements must be removed.

When writing in plain HTML, <span class="e-bolt-button__icon-before"> and <span class="e-bolt-button__icon-after"> are required to wrap around the icon markup. The wrapper ensures that the icon will always wrap with the final word of the text. It will never wrap to the next line on its own.

Demo

Twig

// Icon vars
{% set icon_custom %}
  <img src="/images/placeholders/500x500.jpg">
{% endset %}
{% set icon_chevron_down %}
  {% include '@bolt-elements-icon/icon.twig' with {
    name: 'chevron-down',
  } only %}
{% endset %}

// Button include
{% include '@bolt-elements-button/button.twig' with {
  content: 'This is a button with icons before and after',
  icon_before: icon_custom,
  icon_after: icon_chevron_down,
  attributes: {
    type: 'button'
  }
} only %}

HTML

<button type="button" class="e-bolt-button"><span class="e-bolt-button__icon-before"><!-- Icon or image markup --></span>This is a button with icons before and after<span class="e-bolt-button__icon-after"><!-- Icon or image markup --></span></button>

Icon Only Button

Icon only button visually hides the text content of the button. Such a button should be used sparingly and only in places where screen real estate is a concern.

Important Notes:

It is recommended that icon only buttons to be used in tandem with tooltip to give the user more context about the button’s function.

When writing in plain HTML, aria-label is required to render the button text. For example: <button type="button" class="e-bolt-button e-bolt-button--icon-only" aria-label="Download">. Text should not be used inside the button when using aria-label.

When writing in plain HTML, <span class="e-bolt-button__icon-center"> is required to wrap around the icon markup. The wrapper ensures that the icon will always center within the button.

Demo

File size: 25MB

Add another row

Twig

// Icon only button combined with tooltip
{% set icon_download %}
  {% include '@bolt-elements-icon/icon.twig' with {
    name: 'download',
  } only %}
{% endset %}
{% set tooltip_trigger %}
  {% include '@bolt-elements-button/button.twig' with {
    content: 'Download',
    icon_only: icon_download,
    attributes: {
      type: 'button'
    }
  } only %}
{% endset %}
{% include '@bolt-components-tooltip/tooltip.twig' with {
  trigger: tooltip_trigger,
  content: 'File size: 25MB',
} only %}

HTML

// Icon only button combined with tooltip
<bolt-tooltip>
  <button type="button" class="e-bolt-button e-bolt-button--icon-only" aria-label="Download">
    <span class="e-bolt-button__icon-center"><!-- Icon or image markup --></span>
  </button>
  <span slot="content">File size: 25MB</span>
</bolt-tooltip>

Button Hierarchy

A button can be assigned to various levels of the content hierarchy based on the information architecture of the layout.

Important Notes:

Transparent button is the lowest in the hierarchy level. This style has the lowest affordances and it should NEVER be used alone. Always pair it with a primary, secondary, or tertiary button.

Demo

Light

Dark

Twig

{% include '@bolt-elements-button/button.twig' with {
  content: 'This is a secondary button',
  hierarchy: 'secondary',
  attributes: {
    type: 'button'
  }
} only %}

HTML

<button type="button" class="e-bolt-button e-bolt-button--secondary">This is a secondary button</button>

Button Size

A button’s size can be modified per use case.

Demo

Twig

{% include '@bolt-elements-button/button.twig' with {
  content: 'This is a small button',
  size: 'small',
  attributes: {
    type: 'button'
  }
} only %}

HTML

<button type="button" class="e-bolt-button e-bolt-button--small">This is a small button</button>

Button Border Radius

Rounded buttons are possible with the border_radius prop.

Demo

Twig

{% include '@bolt-elements-button/button.twig' with {
  content: 'This is a fully rounded button',
  border_radius: 'full',
  attributes: {
    type: 'button'
  }
} only %}

HTML

<button type="button" class="e-bolt-button e-bolt-button--border-radius-full">This is a fully rounded button</button>

Button Display

The display of a button can be changed from inline to block (full width), and there is an extra option to make it transform from inline to block at the small breakpoint.

Important Notes:

When display prop is set to inline@from-small, it means the button is block display below the small breakpoint, and transform to inline display from small breakpoint and up. Resize the browser to see the demo below.

Demo

Twig

{% include '@bolt-elements-button/button.twig' with {
  content: 'This is a full width button',
  display: 'block',
  attributes: {
    type: 'button'
  }
} only %}

HTML

<button type="button" class="e-bolt-button e-bolt-button--block">This is a full width button</button>

Upload Button

The button classes can also be used on a file input.

Important Notes:

This is an advanced use case and the Twig template does not support this.

Hierarchy should be set to tertiary.

Size should be set to small.

Demo

Twig

Not available in Twig. Please use plain HTML.

HTML

<input id="unique-file-id" type="file" class="e-bolt-button e-bolt-button--small e-bolt-button--tertiary">

button

button docs

Button

A graphical element that indicates interactivity.

button

button link

button attributes

button with icon

button with icon only

button hierarchy

button size

button border radius

button display

button upload

button

button docs Show Code Hide Code

Button

A graphical element that indicates interactivity.

button Show Code Hide Code

button link Show Code Hide Code

button attributes Show Code Hide Code

button with icon Show Code Hide Code

button with icon only Show Code Hide Code

button hierarchy Show Code Hide Code

button size Show Code Hide Code

button border radius Show Code Hide Code

button display Show Code Hide Code

button upload Show Code Hide Code

button docs

button

button link

button attributes

button with icon

button with icon only

button hierarchy

button size

button border radius

button display

button upload