Skip to main content

Pivotal UI

v18.0.0
Components / Buttons

Buttons

Use buttons as triggers for actions. Try to avoid the usage of buttons for navigation. The main difference between actions and navigation is that actions are operations performed on objects, while navigation refers to elements on the screen or view that take you to another context in the application. For navigation, consider simply using links.

Pivotal UI provides four kinds of buttons: primary buttons, default buttons, danger buttons, and brand buttons. See below for examples.

By default, each button is designed to have accessible color contrast over light backgrounds (white or light-gray). To use a button over a dark background (black or dark-gray), see the examples below.

Button types

Primary buttons should be used for the main action of a view, eg. a page, flyout, or modal. There will likely only be one of these on-screen at a time.

Primary button
ReferenceError: React is not defined

If completing this action can have destructive effects, such as deletion, use a danger button. Like primary buttons, danger buttons draw attention. Both indicate the main action, so use only one or the other per view.

Danger button
ReferenceError: React is not defined

Use a default button for other actions that could be taken on a view.

Default button
ReferenceError: React is not defined

Brand buttons can be used to incorporate Pivotal's teal color. In most cases, one of the other three button types should be used instead.

Brand button
ReferenceError: React is not defined

Usage on dark backgrounds

Buttons that appear over dark backgrounds are styled differently to achieve accessible color contrast. To make a button accessible against a dark background, set the onDark prop.

Using the onDark prop
ReferenceError: React is not defined

Alternatively, you can wrap components in the ThemeProvider component.

Common button patterns

When an action can be cancelled (e.g. closing a payment modal without completing the transaction), use a pair of buttons. The button on the left should have alt and should allow the user to cancel the workflow. The button on the right should confirm the action and should not have the alt prop.

Typical cancel & confirm buttons
ReferenceError: React is not defined

When the action is destructive, follow the same pattern with danger buttons.

Cancel & delete danger buttons
ReferenceError: React is not defined

For a button that performs a non-essential action, set the flat prop to remove the background and the border.

Flat buttons
ReferenceError: React is not defined

Set the icon prop to add an icon next to the button text.

Button with icon
ReferenceError: React is not defined

By default, the icon appears to the left of the text. To place the icon on the right, set the iconPosition prop to "right".

Button with right icon
ReferenceError: React is not defined

To use a button with an icon and no text, set the iconOnly prop to make spacing even around the icon. Since they do not have text content, icon-only buttons must have an aria-label set so that screen readers understand their purpose.

Icon-only buttons
ReferenceError: React is not defined

Set the disabled prop on a button to prevent a user from interacting with it.

Disabled button
ReferenceError: React is not defined

Set the large or small prop to increase or decrease the size of the button. In most cases use the default size.

Sizing
ReferenceError: React is not defined

Set the fullWidth prop to make the button take up the full width of its container. This is useful for responsive layouts.

Full-width button
ReferenceError: React is not defined

A common pattern is to have a button that triggers an action, then is disabled and shows a spinner until the action completes. This can be achieved with the icon and disabled props.

Submit button
ReferenceError: React is not defined

Props

PropertyRequiredTypeDefaultDescription
altnoBooleanfalseWhether to render as 'alternate' button
flatnoBooleanfalseWhether to render as a 'flat' button
fullWidthnoBooleanfalseWhether to render the button full width
hrefnoStringIf specified, button will be rendered as an <a> tag with button-like styling that links to this href
iconOnlynoBooleanfalseIf specified, will render as an icon button
iconPositionno"left" or "right""left"If specified, places the icon to the left or the right of the text and or children
largenoBooleanfalseWhether to render the button large
smallnoBooleanfalseWhether to render the button small

Imports

Import React components (including CSS):

import {DefaultButton, PrimaryButton, DangerButton, BrandButton} from 'pivotal-ui/react/buttons';

Import CSS only:

import 'pivotal-ui/css/buttons';