o3-button

o3-button includes button, button group, and pagination patterns. See our design guidelines for usage information and brand support.

- o3-button
- Markup
- Types
- Themes
- Sizes
- Fluid, full width
- Icons
- Groups
- Pagination
- Disabled
- JSX
- Migration
- Contact
- Licence

Markup

o3-button supports JSX templates for React users, or direct HTML. We recommend using JSX where possible.

$3

There are three types of buttons, primary, secondary, and ghost. When to use which button type is described in our design guidelines.

| Type | Selector |
| --------- | --------------------- |
| primary | .o3-button--primary |
| secondary | .o3-button--secondary |
| ghost | .o3-button--ghost |

``html
Submit
Cancel
Options
`

o3-button may be used with either or elements.

$3

A theme may be applied to a button to change its appearance using the data-o3-theme. See our design guidelines for a list of available themes for your brand. Examples include:

| Theme | Data attribute |
| ------- | ----------------------- |
| inverse | data-o3-theme="inverse" |
| mono | data-o3-theme="mono" |

Themes may be applied on a parent element, for all components within to inherit. E.g. for an FT Professional brand button, with inverse theme:

`html




Inverse professional button


`

Or, themes may be applied specifically to a single button:

`html


Inverse professional button


`

$3

Apply the o3-button--small modifier class for a smaller button, as appropriate, inline with design guidelines.

`html
Click me
`

$3

Apply the data-o3-fluid data attribute to make buttons "fluid", and expand to the full width of their container. By default this applies only to small, mobile viewports. On larger viewports a fluid button's width is based on its content by default.

`html
Click me
`

For more control on when a button should be full width set the --o3-button-fluid CSS Custom Property. For example:

Force buttons to always be full width, given they are a direct child of a "my-button-container" element.

`css
.my-button-container > .o3-button {
--o3-button-fluid: initial;
}
`

Make buttons full width using a container query, given a "my-button-container" parent element that is less than 500px wide.

`css
.my-button-container {
container-type: inline-size;
}

@supports (container-type: inline-size) {
@container (width < 500px) {
.my-button-container > .o3-button {
--o3-button-fluid: initial;
}
}
}
`

$3

#### Icon and label

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

A limited number of button icons are available. Limiting the number of icons keeps the CSS bundle smaller.

If you need an icon button that we don't currently support, please contact the Origami team.

`html
class="o3-button o3-button--secondary o3-button-icon o3-button-icon--chevron-down"
>
Chevron down arrow

class="o3-button o3-button--secondary o3-button-icon o3-button-icon--download"
>
Download

`

#### Icon position

Button icons may be positioned to the right where the icon indicates direction or continuation. Add the o3-button-icon--end CSS modifier. See button design guidelines for more details.

`html
class="o3-button o3-button--primary o3-button-icon o3-button-icon--chevron-down o3-button-icon--end"
>
Continue

`

#### Icon only

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

`html
class="o3-button o3-button--secondary o3-button-icon o3-button-icon--chevron-down o3-button-icon--icon-only"
>
Chevron down arrow

`

#### Custom icons

If you want to use icons not in the o3-button supported icons list talk to Origami team and we will direct you to existing icon or help you to adopt the new icon. Alternatively, your icon may make a suitable addition to our standard set.

After discussing together, we may decide a custom icon is the most appropriate option. In which case, set the --o3-button-icon custom property with a URL encoded SVG of your icon:

`css
.my-button-modifier-class {
--o3-button-icon: url('data:image/svg+xml,[ENCODED_SVG_STRING]');
}
`

`html
class="o3-button o3-button--secondary o3-button-icon my-button-modifier-class"
>
My custom icon button

`

$3

Wrap buttons in a container with .o3-button-group to group them together:

`html



`

$3

Our pagination pattern varies according to the space available to it, e.g. mobile vs. desktop devices.

We recommend using our JSX template where possible. Alternatively, you must re-implement pagination logic following our pagination design guidelines.

data-o3-button-show-when is used to show/hide pagination elements according to the space available. Here is example markup for pagination with 10 pages, where the 5th page is selected.

`html



`

Again, we recommend using our JSX template where possible instead of re-implementing the logic described in our pagination design guidelines.

$3

Avoid disabled buttons unless user research shows they improve your interface, see our buttons usage guidelines for more.

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

`html

My Button


My Button
`

JSX

For React users, Origami components now include JSX templates. Import JSX templates along with component CSS. JSX templates are exported as cjs (common JS) and esm (ECMAScript) modules, so depending on your system configuration, you may need to import the correct module type.

See Storybook for full o3-button JSX documentation.

For example, for a primary button:

`jsx
import {Button} from '@financial-times/o3-button/cjs';

import '@financial-times/o3-button/css/[your brand].css';

;
`

For pagination:

`jsx
import {ButtonPagination} from '@financial-times/o3-button/cjs';

import '@financial-times/o3-button/css/[your brand].css';

;
``

Migration

| State | Major Version | Last Minor Release | Migration guide |
| :----------: | :-----------: | :----------------: | :---------------------------------------------------: |
| ✨ active | 3 | N/A | migrate to v3 |
| ╳ deprecated | 2 | 2.0 | migrate to v2 |
| ╳ deprecated | 1 | 1.1 | - |

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.