o-buttons 
o-buttons provides Sass mixins and variables to create buttons.
Quick start
o-buttons provides styling for:
Themes
The secondary
theme is the default o-buttons
theme.
To apply a theme use one of the above selectors e.g. o-buttons o-buttons--inverse
, or if using Bower and silent mode @include oButtonsTheme($theme);
. Using Sass Mixins custom themes are also supported.
Sizes
o-buttons--{default|big}
or @include oButtonsSize($size);
Grouped buttons
.o-buttons-group
or @include oButtonsGroup;
Pagination buttons
.o-buttons-pagination
or @include oButtonsPagination;
Icon buttons
.o-buttons-icon .o-buttons-icon--{arrow-left| arrow-right | other supported icon}
or @include oButtonsIconButton($icon-name, $size, $theme);
You can combine these styles.
Usage
For design guidelines, see the registry.
For detailed documentation on this component's mixins, see the Sassdoc
Markup
The button CSS will work on <button>
or <a>
elements. It is important for accessibility that if you intend to style an <a>
as a button, you give it the correct aria role.
Sass
Mixins, Custom themes and silent mode are only available if you're including o-buttons in your project using bower. If you're using o-buttons via the Build Service, you must use the o-buttons classes instead. Both are documented below.
Default button
<!-- Default/Secondary theme, default size -->
<button class="o-buttons">Secondary</button>
Or, using Sass:
.my-button-class {
@include oButtons();
}
<!-- Default/Secondary theme, default size -->
<button class="my-button-class">Secondary</button>
States
<!-- Default/Secondary theme, default size -->
<button class="o-buttons">Secondary</button>
<button class="o-buttons" aria-selected="true">Selected</button>
<button class="o-buttons" aria-pressed="true">Pressed</button>
<button class="o-buttons" disabled>Disabled</button>
Grouped buttons
<div class="o-buttons-group">
<button class="o-buttons">John</button><!--
--><button class="o-buttons">Paul</button><!--
--><button class="o-buttons">George</button><!--
--><button class="o-buttons">Ringo</button>
</div>
Or, using Sass:
.my-button-group-class {
@include oButtonsGroup('my-button-class');
}
<div class="my-button-group-class">
<button class="my-button-class">John</button><!--
--><button class="my-button-class">Paul</button><!--
--><button class="my-button-class">George</button><!--
--><button class="my-button-class">Ringo</button>
</div>
Pagination buttons
<div class="o-buttons-pagination">
<button class="o-buttons">1</button><!--
--><button class="o-buttons">2</button><!--
--><button class="o-buttons">3</button><!--
--><button class="o-buttons">4</button>
</div>
Or, using Sass:
.my-button-pagination-class {
@include oButtonsPagination(my-button-class);
}
<div class="my-button-pagination-class">
<button class="my-button-class">1</button><!--
--><button class="my-button-class">2</button><!--
--><button class="my-button-class">3</button><!--
--><button class="my-button-class">4</button>
</div>
Size modifiers
<button class="o-buttons">Default-sized button</button>
<button class="o-buttons o-buttons--big">Big button</button>
Or, using Sass:
.my-button-class {
@include oButtons();
}
.my-button-class--big {
@include oButtonsSize(big);
}
// Or…
.my-big-button {
@include oButtons(big);
}
<button class="my-button-class my-button-class--big">Big button</button>
<button class="my-big-button-class">Big button</button>
Theme modifiers
There are named themes in o-buttons
. o-buttons
also allows developers to create custom themes using o-colors names.
<button class="o-buttons o-buttons--primary">Primary button</button>
<button class="o-buttons">Default/Secondary button</button>
<button class="o-buttons o-buttons--mono">Mono button</button>
<button class="o-buttons o-buttons--inverse">Inverse button</button>
<button class="o-buttons o-buttons--b2c">B2C button</button>
More named themes are demonstrated in the registry.
Or, using Sass:
.my-button-class {
@include oButtons();
}
.my-button-class--secondary {
@include oButtonsTheme(secondary);
}
// Or…
.my-secondary-button {
@include oButtons($theme: secondary);
}
<button class="my-button-class my-button-class--secondary">Secondary button</button>
<button class="my-secondary-button">Secondary button</button>
Custom themes
oButtonsTheme also accepts a Map, which you can use to create your own themes. The Map can have the following keys:
background
: [String] - the backgroundo-colors
color for the place the button sits on.accent
: [String] - the accento-colors
color for the button.hover
: [String] - an optional parameter for the button hover state. It requires ano-colors
color. Defaults to a mix of thebackground
andaccent
colors.colorizer
: [String] - an optional parameter for the button style. One of "primary" or "secondary". Defaults to secondary.
To create a lemon
accented button on a slate
background:
@include oButtonsTheme($theme: (background: 'slate', accent: 'lemon', colorizer: 'primary'));
This will output styles for a slate coloured button that has lemon text and border, with a slate/lemon mixed hover state.
To create a lemon
filled button on a slate
background, use the colorizer
parameter and set to primary
:
@include oButtonsTheme($theme: (background: 'slate', accent: 'lemon', colorizer: 'primary'));
This will output styles for a lemon coloured button that has slate text, with a slate/lemon mixed hover state.
Icons
If you're using bower, you can create an icon button for any icon in fticons.
If you're using the Build Service, currently supported icons are defined in the $o-buttons-icons
variable in scss/_variables.scss
. Limiting the concrete classes keeps the compiled CSS bundle small, but if you need an icon button that we don't currently support then please open an issue.
// Icon and text button.
<button class="o-buttons o-buttons-icon o-buttons-icon--arrow-left">Go left</button>
// Icon only button
<button class="o-buttons o-buttons-icon o-buttons-icon--icon-only o-buttons-icon--arrow-left">
// accessible text fallback for the button. Not visible, only required for icon only buttons.
<span class="o-buttons-icon__label">Go left</span>
</button>
Or, using Sass:
.my-button-class--icon {
@include oButtons();
@include oButtonsIconButton($icon-name: star);
}
.my-button-class--icon-only {
@include oButtons();
@include oButtonsIconButton($icon-name: star, $is-icon-only: true);
}
// Icon and text button.
<button class="my-button-class--icon">star</button>
// Icon only button
<button class="my-button-class--icon-only">
<!-- accessible text fallback for the button. Not visible, only required for icon only buttons. -->
<span class="my-button-class-icon__label">star</span>
</button>
Troubleshooting
In the past we've seen issues where adding styles to the background
property of buttons with a low specificity selector can overwrite the background-color
styles added by o-buttons, see issue #76. This happens because o-buttons styles the background-color
property on buttons to add color instead of the shorthand property, which allows for icons to be added to buttons using the remaining background properties.
To avoid this, use the background-color
property instead of the shorthand background
property if you wish to overwrite a buttons background-color.
Migration Guide
Migrating from v4 to v5
This major includes the new o-colors and updates the themes and sizes of buttons.
Sizes have been updated to default
(28px
min-height), and big
(40px
min-height) to correspond to the new baseline sizing introduced in the new o-typography. Small
button size has been removed.
The following changes have been made to the themes:
Standard
is nowSecondary
and the default button style: useo-buttons
oro-buttons--secondary
classesStandout
is nowPrimary
: useo-buttons--primary
classUncolored
is nowMono
: useo-buttons--mono
class
Inverse and B2C themes have remained the same.
Removes deprecated classnames:
-.o-buttons__pagination
+.o-buttons-pagination
-.o-buttons__group
+.o-buttons-group
Contact
If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #ft-origami or email Origami Support.
Licence
This software is published by the Financial Times under the MIT licence.