Origami Frontend Components & Services

Readme: o-buttons

o-buttons provides Sass mixins and variables to create buttons.

Usage

Check out how to include Origami components in your project to get started with o-buttons.

Markup

There are two types of buttons, primary buttons and secondary buttons.

Type Selector Brand Support
primary .o-buttons--primary master, internal, whitelabel
secondary .o-buttons--secondary master, internal, whitelabel
<button class="o-buttons o-buttons--primary">Submit</button>
<button class="o-buttons o-buttons--secondary">Cancel</button>

o-buttons 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.

Themes

A theme may be applied to a button to change its appearance. o-buttons provides some themes by default:

Theme Selector Works With Types Brand Support
inverse .o-buttons--inverse primary, secondary master, internal
mono .o-buttons--mono primary, secondary master, internal
b2c .o-buttons--b2c primary master
<button class="o-buttons o-buttons--primary o-buttons--inverse">Submit</button>
<button class="o-buttons o-buttons--secondary o-buttons--inverse">Cancel</button>

Sass users may create custom themes.

Sizes

Any button may be made larger using the o-buttons--big modifier class.

<button class="o-buttons o-buttons--primary o-buttons--big">Click Me</button>

Icons

To add an icon to your button add the class o-buttons-icon and o-buttons-icon--{icon-name} to your button.

Sass users may output any icon from the fticons set. However if you're using the Build Service a limited number of button icons are available. Limiting the number of icons keeps the CSS bundle smaller, but if you need an icon button that we don't currently support then please contact the Origami team:

<button class="o-buttons o-buttons--secondary o-buttons-icon o-buttons-icon--arrow-down">Down Arrow</button>
<button class="o-buttons o-buttons--secondary o-buttons-icon o-buttons-icon--download">Download</button>

If you would like your button to display only an icon, add the class o-buttons-icon--icon-only and provide a visually hidden label for screen-reader users with o-buttons-icon__label.

<button class="o-buttons o-buttons--secondary o-buttons-icon o-buttons-icon--arrow-down o-buttons-icon--icon-only">
    <span class="o-buttons-icon__label">
        Down Arrow
    </span>
</button>

Groups

Wrap buttons with .o-buttons-group to group them together:

<div class="o-buttons-group">
    <button class="o-buttons o-buttons--secondary" aria-selected="true">One</button>
    <button class="o-buttons o-buttons--secondary">Two</button>
    <button class="o-buttons o-buttons--secondary">Three</button>
</div>

Pagination

For a pagination style wrap your buttons in .o-buttons-pagination. Most pagination usecases use an anchor a tags for links which look like buttons instead of a button tag. When using an anchor tag in pagination do not use the aria-selected data attribute. Instead use aria-current="page" to indicate the current page, this will highlight the button for the current page visually and to screen readers.

The following markup example shows pagination for 20 pages, where the 14th page is the current page. Following the pagination rules we recommend displaying no more than 7 pages and using the ellipsis element to show hidden results.

<div class="o-buttons-pagination">
    <a href="#" class="o-buttons o-buttons--secondary o-buttons-icon o-buttons-icon--arrow-left o-buttons-icon--icon-only">
        <span class='o-buttons-icon__label'>Fewer results</span>
    </a>

    <a href="#" class="o-buttons o-buttons--secondary">1</a>
    <span class="o-buttons-pagination__ellipsis">...</span>
    <a href="#" class="o-buttons o-buttons--secondary">13</a>
    <a href="#" class="o-buttons o-buttons--secondary" aria-current="page">14</a>
    <a href="#" class="o-buttons o-buttons--secondary">15</a>
    <span class="o-buttons-pagination__ellipsis">...</span>
    <a href="#" class="o-buttons o-buttons--secondary">20</a>

    <a href="#" class="o-buttons o-buttons--secondary o-buttons-icon o-buttons-icon--arrow-right o-buttons-icon--icon-only">
        <span class='o-buttons-icon__label'>More results</span>
    </a>
</div>

Pagination Rules

The number of pages to display is not enforced by Origami. However we recommend the following:

For an example see the pagination demos in the Origami registry.

Pagination Theme

A theme modifier such as o-buttons--inverse may be added to the buttons within a pagination block.

Pagination Size

Big buttons may also be used in a pagination style. Add the o-buttons--big modifier to each button and o-buttons-pagination__ellipsis--big to the ellipsis element.

<div class="o-buttons-pagination">
    <a href="#" class="o-buttons o-buttons--big o-buttons--secondary o-buttons-icon o-buttons-icon--arrow-left o-buttons-icon--icon-only" disabled>
        <span class='o-buttons-icon__label'>Fewer results</span>
    </a>

    <a href="#" class="o-buttons o-buttons--big o-buttons--secondary" aria-current="page">1</a>
    <a href="#" class="o-buttons o-buttons--big o-buttons--secondary">2</a>
    <a href="#" class="o-buttons o-buttons--big o-buttons--secondary">3</a>
    <span class="o-buttons-pagination__ellipsis o-buttons-pagination__ellipsis--big">...</span>
    <a href="#" class="o-buttons o-buttons--big o-buttons--secondary">18</a>
    <a href="#" class="o-buttons o-buttons--big o-buttons--secondary">19</a>
    <a href="#" class="o-buttons o-buttons--big o-buttons--secondary">20</a>

    <a href="#" class="o-buttons o-buttons--big o-buttons--secondary o-buttons-icon o-buttons-icon--arrow-right o-buttons-icon--icon-only">
        <span class='o-buttons-icon__label'>More results</span>
    </a>
</div>

Disabled

Avoid disabled buttons unless user research shows they improve your interface. Disabled buttons have poor contrast which makes them difficult to read. They also do not give feedback to a user why they are disabled.

To make a button disabled add the disabled attribute. To visually hide the disabled button until it is active add the class o-buttons--hide-disabled.

<!-- Visibly disabled because of the `disabled` attribute. -->
<button class="o-buttons" disabled>My Button</button>

<!-- Visually hidden because of the `disabled` attribute and `o-buttons--hide-disabled`.-->
<button class="o-buttons o-buttons--hide-disabled" disabled>My Button</button>

Sass

To output default o-buttons CSS make a single call to the primary mixin oButtons. It is recommended that you pass an options map as the first argument to include only the button styles you need. Without the options map, all o-buttons styles are included.

@include oButtons($opts: (
    'sizes': ('big'), // e.g .o-buttons--big
    'types': ('primary', 'secondary'), // e.g .o-buttons--primary
    'themes': ('mono', 'inverse', 'b2c'), // e.g .o-buttons--inverse
    'icons': ('arrow-left', 'arrow-right', 'search'), // any fticons, e.g .o-buttons-icons.o-buttons-icons--search
    'pagination': true, // .o-buttons-pagination
    'groups': true // .o-buttons-group
));

Custom Themes

To create a new button theme call oButtonsAddTheme with the colour of your theme along with the types of buttons and icons you would like to use with your theme, if any.

/// .o-buttons--my-special-button
@include oButtonsAddTheme(
    $name: 'my-special-button',
    $opts: ('color': 'claret-80'),
    $types: ('primary', 'secondary'),
    $icons: ('arrow-up', 'arrow-down')
);

Custom Markup

We recommend using o-buttons markup as this encourages CSS reuse and smaller bundle sizes. If you are unable to update your markup to use o-buttons classes, including those generated by oButtonsAddTheme, use oButtonsContent:

.my-button {
    @include oButtonsContent($opts: ('type': 'primary'));
}
.my-icon-button {
    @include oButtonsContent($opts: (
        'type': 'primary',
        'icon': 'arrow-right'
    ));
}
.my-lemon-button {
    @include oButtonsContent($opts: (
        'type': 'primary',
        'theme': ('color': 'lemon')
    ));
}

oButtonsContent has options to recreate all buttons, including for different sizes and icon only buttons. See the o-buttons SassDoc for more details and examples.

References

Migration

State Major Version Last Minor Release Migration guide
✨ active 7 N/A migrate to v7
⚠ maintained 6 6.2 migrate to v6
╳ deprecated 5 5.16 migrate to v5
╳ deprecated 4 4.5 -
╳ deprecated 3 3.1 -
╳ deprecated 2 2.0 -
╳ deprecated 1 1.8 -

Contact

If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #origami-support or email Origami Support.


Licence

This software is published by the Financial Times under the MIT licence.

Status
active
Switch component view

GitHub Repository

Install o-buttons

If using the Build Service, add o-buttons@^7.0.0 to your link tag.

If using the npm package manager for a Manual Build, run npm install --save-peer "@financial-times/o-buttons@^7.0.0".

Help & Support

o-buttons is maintained directly by the Origami team. If you have any questions about o-buttons or Origami in general, we are happy to help. 😊

Slack: #origami-support
Email: origami.support@ft.com

Feedback / Issues

To report a bug or request features please create an issue on Github. For support or general feedback please get in touch 😊

Slack: #origami-support
Email: origami.support@ft.com