Readme: 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

View demos

<!-- 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

View demos

<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

View demos

<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 background o-colors color for the place the button sits on.
• accent: [String] - the accent o-colors color for the button.
• hover: [String] - an optional parameter for the button hover state. It requires an o-colors color. Defaults to a mix of the background and accent 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 now Secondary and the default button style: use o-buttons or o-buttons--secondary classes
• Standout is now Primary: use o-buttons--primary class
• Uncolored is now Mono: use o-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.