Documentation of buttons and its variations, including icons in buttons.
There are also button layouts, groups and some extended functionality for dropdown and split buttons.
Files
app/styles/modules/_buttons.scss
Icons in buttons
Icons are added to button by creating icon element same way as described in icons. There are two ways how to use icons in buttons - inline or positioned.
Floating icons
Inline icons sit in line with text. Classes .icon--left
and .icon--right
on the icon element add proper spacing.
Small icon and text
Medium icon and text
Large button and small button
Only icons
<!-- small icon and text -->
<button type="button" class="btn">
<svg class="icon icon-download icon--small icon--left" role="img" aria-hidden="true">
<use xlink:href="#icon-download"></use>
</svg> Download
</button>
<button type="button" class="btn btn--primary"> Settings
<svg class="icon icon--settings icon--small icon--right" role="img" aria-hidden="true">
<use xlink:href="#icon-settings"></use>
</svg>
</button>
<!-- medium icon and text -->
<button type="button" class="btn btn--primary">
<svg class="icon icon-download icon--medium icon--left" role="img" aria-hidden="true">
<use xlink:href="#icon-download"></use>
</svg> Download
</button>
<button type="button" class="btn"> Settings
<svg class="icon icon--settings icon--medium icon--right" role="img" aria-hidden="true">
<use xlink:href="#icon-settings"></use>
</svg>
</button>
<!-- large and small button -->
<button type="button" class="btn btn--primary btn--small">
<svg class="icon icon-download icon--small icon--left" role="img" aria-hidden="true">
<use xlink:href="#icon-download"></use>
</svg> Download
</button>
<button type="button" class="btn btn--large"> Settings
<svg class="icon icon--settings icon--medium icon--right" role="img" aria-hidden="true">
<use xlink:href="#icon-settings"></use>
</svg>
</button>
<!-- only icons -->
<button type="button" class="btn">
<svg class="icon icon-home icon--small" role="presentation" aria-label="Home">
<use xlink:href="#icon-home"></use>
</svg>
</button>
<button type="button" class="btn btn--primary">
<svg class="icon icon-facebook icon--medium" role="presentation" aria-label="Facebook">
<use xlink:href="#icon-facebook"></use>
</svg>
</button>
<button type="button" class="btn btn--link">
<svg class="icon icon-edit icon--medium" role="presentation" aria-label="Edit">
<use xlink:href="#icon-edit"></use>
</svg>
</button>
Positioned icons
Unlike inline icons, positioned icons are set using classes .btn--icon-left
and .btn--icon-right
on button element. The icon sits outside regular text area at the side of the button.
<button type="button" class="btn btn-full btn--icon-left">
<svg class="icon icon-chevronleft icon--large" role="img" aria-hidden="true">
<use xlink:href="#icon-chevronleft"></use>
</svg>
</button>
<button type="button" class="btn btn--primary btn-full btn--icon-right"> Next
<svg class="icon icon-chevronright icon--large" role="img" aria-hidden="true">
<use xlink:href="#icon-chevronright"></use>
</svg>
</button>
<button type="button" class="btn btn--large btn-full btn--icon-left">
<svg class="icon icon-chevronleft icon--large" role="img" aria-hidden="true">
<use xlink:href="#icon-chevronleft"></use>
</svg>
</button>
<button type="button" class="btn btn--small btn--primary btn-full btn--icon-right"> Next
<svg class="icon icon-chevronright icon--large" role="img" aria-hidden="true">
<use xlink:href="#icon-chevronright"></use>
</svg>
</button>
Layouts
There are two button layouts: horizontal and vertical. Layouts can vary by breakpoint.
Button layout
Button layouts are created by wrapping buttons in .btn-layout--vertical
or .btn-layout--horizontal
.
You can specify on which breakpoint the default behavior changes by using .btn-layout--[breakpoint]-vertical
and .btn-layout--[breakpoint]-horizontal
Note
Horizontal button layout is also compatible with grid horizontal alignment classes. Use them to move your buttons to the center or right of the layout.
Buttons are stacked vertically by default, on medium screens the layout becomes horizontal and then vertical again on XL.
<div class="btn-layout--vertical btn-layout--m-horizontal btn-layout--xl-vertical">
<button type="button" class="btn">Button</button>
<button type="button" class="btn">Button</button>
<button type="button" class="btn">Button</button>
</div>
Groups
Button groups merge related buttons into more complex components.
Button groups
Button groups are be created by wrapping buttons into .btn-group--horizontal
or .btn-group--vertical
.
Button groups can change their orientation on breakpoints. Just use .btn-group--[breakpoint]-horizontal
and .btn-group--[breakpoint]-vertical
.
Note
Horizontal button group is also compatible with grid horizontal alignment classes. Use them to move your buttons to the center or right of the group.
Button groups horizontal
Button groups vertical
<div class="btn-group--horizontal">
<button class="btn" type="button">Button</button>
<button class="btn" type="button">Button</button>
<button class="btn" type="button">Button</button>
</div>
<div class="btn-group--horizontal"> ... </div>
<div class="btn-group--horizontal"> ... </div>
<div class="btn-group--vertical">
<button class="btn" type="button">Button</button>
<button class="btn" type="button">Button</button>
<button class="btn" type="button">Button</button>
</div>
<div class="btn-group--vertical"> ... </div>
<div class="btn-group--vertical"> ... </div>
Dropdown and split buttons
Dropdown and split buttons are custom button components with extended functionality. While dropdowns provide extended options of action in dropdown menu, split buttons have these options separated from main action into second part of button.
Note
Dropdown and split buttons uses Dropdown component.
Warning
Split buttons and dropdowns use Toggle.js javascript module. Do not forget tu use attribute [data-toggle]
to activate toggle functionality. Use attributes other like data-toggle-icon
and data-toggle-expand
to setup buttons.
Javascript dependency
Split and dropdown button components require:
Toggle javascript module:app/scripts/modules/Toggle.js
.
Initialized by default in: app/scripts/main.js
file.
Dropdown buttons
Dropdown buttons are created by wrapping button and dropdown list into element with class .btn-dropdown
. Exact examples are shown below.
Note
Dropdown buttons are also used in button layouts same way as normal buttons.
Warning
Dropdown buttons are not supported in button groups.
<div class="btn-dropdown">
<button
class="btn"
data-toggle="self, next" data-toggle-icon="#icon-chevronup"
data-toggle-expand
aria-haspopup="true"
>Button<svg class="icon icon-chevrondown icon-dropdown" role="img" aria-hidden="true">
...
</button>
<div class="dropdown" data-dropdown data-toggle-expand>
...
</div>
</div>
<div class="btn-dropdown">
<button
class="btn btn--primary btn--large"
data-toggle="self, next"
data-toggle-icon="#icon-chevronup"
data-toggle-expand
aria-haspopup="true"
>Button<svg class="icon icon-chevrondown icon-dropdown" role="img" aria-hidden="true">
...
</button>
<div class="dropdown" data-dropdown data-toggle-expand>
...
</div>
</div>
<div class="btn-dropdown">
<button
class="btn--small"
disabled
data-toggle="self, next"
data-toggle-icon="#icon-chevronup"
data-toggle-expand
aria-haspopup="true"
>Button<svg class="icon icon-chevrondown icon-dropdown" role="img" aria-hidden="true">
...
</button>
<div class="dropdown" data-dropdown data-toggle-expand>
...
</div>
</div>
Split buttons
Split buttons are basicaly extended dropdown buttons. They are created the same way as dropdowns, but using the call .btn-dropdown-split
and instead of using one button, you will use two.
Warning
Split buttons are not supported in button groups and button bars.
<div class="btn-dropdown-split">
<button class="btn">Button</button>
<button
class="btn btn--equal"
data-toggle="self, next, parent" data-toggle-icon="#icon-chevronup"
data-toggle-expand
aria-haspopup="true"
>
...
</button>
<div class="dropdown" data-toggle-expand>
...
</div>
</div>
<div class="btn-dropdown-split">
<button class="btn btn--large">Button</button>
<button
class="btn btn--large"
data-toggle="self, next, parent"
data-toggle-icon="#icon-chevronup"
data-toggle-expand
aria-haspopup="true"
>
...
</button>
<div class="dropdown" data-toggle-expand>
...
</div>
</div>
<div class="btn-dropdown-split is-disabled">
<button class="btn btn--small" disabled>Button</button>
<button
class="btn btn--small"
disabled data-toggle="self, next, parent"
data-toggle-icon="#icon-chevronup"
data-toggle-expand
aria-haspopup="true"
>
...
</button>
<div class="dropdown" data-toggle-expand>
...
</div>
</div>