Button

Used to perform an action, such as submitting a form, opening/closing a dialog, or using a cancel action.

• View on Github

• View Core API

• View on Figma

Anatomy

1. Leading Icon (optional)
2. Label
3. Trailing Icon (optional)

Import

import { Button } from '@pluralsight/react'

Usage

Basic Buttons

function BasicButtonExample() {
  return (
    <Grid cols="repeat(6, 1fr)" gap={8}>
      <GridItem>
        <Button>Action</Button>
      </GridItem>

      <GridItem>
        <Button sentiment="default">Default</Button>
      </GridItem>

      <GridItem>
        <Button sentiment="danger">Danger</Button>
      </GridItem>

      <GridItem>
        <Button usage="outline">Outline</Button>
      </GridItem>

      <GridItem>
        <Button usage="text">Text</Button>
      </GridItem>

      <GridItem>
        <Button disabled>Disabled</Button>
      </GridItem>
    </Grid>
  )
}

Outline Buttons

When you need a button that is not the primary focus of the page, use an outline button. To create an outline button, use the usage prop and set it to outline.

function OutlineButtonExample() {
  return (
    <Grid cols="repeat(6, 1fr)" gap={8}>
      <GridItem>
        <Button sentiment="action" usage="outline">
          Action
        </Button>
      </GridItem>

      <GridItem>
        <Button sentiment="default" usage="outline">
          Default
        </Button>
      </GridItem>

      <GridItem>
        <Button sentiment="danger" usage="outline">
          Danger
        </Button>
      </GridItem>

      <GridItem>
        <Button disabled={true} usage="outline">
          Disabled
        </Button>
      </GridItem>
    </Grid>
  )
}

Text Buttons

When you need a button that is not the primary or secondary focus of the page, use a text button. To create a text button, use the usage prop and set it to text.

function TextButtonExample() {
  return (
    <Grid cols="repeat(6, 1fr)" gap={8}>
      <GridItem>
        <Button usage="text">Action</Button>
      </GridItem>

      <GridItem>
        <Button sentiment="default" usage="text">
          Default
        </Button>
      </GridItem>

      <GridItem>
        <Button sentiment="danger" usage="text">
          Danger
        </Button>
      </GridItem>

      <GridItem>
        <Button disabled={true} usage="text">
          Disabled
        </Button>
      </GridItem>
    </Grid>
  )
}

Button with icon

To display an Icon at the start or end of a button, use the startIcon or endIcon prop.

// import { PlaceholderIcon } from '@pluralsight/icons'

function ButtonWithIconExample() {
  return (
    <Grid cols="repeat(5, 1fr)" gap={8}>
      <GridItem>
        <Button startIcon={PlaceholderIcon}>Start icon</Button>
      </GridItem>

      <GridItem>
        <Button endIcon={PlaceholderIcon}>End icon</Button>
      </GridItem>
    </Grid>
  )
}

Sizes

Buttons come in two sizes: m and l. The default size is l.

function ButtonSizes() {
  return (
    <Grid cols="repeat(5, 1fr)" gap={8} data-site-override="alignGridCenter">
      <GridItem>
        <Button size="m">Medium</Button>
      </GridItem>

      <GridItem>
        <Button size="l">Large (default)</Button>
      </GridItem>
    </Grid>
  )
}

Customizing

There are 3 ways to customize the Button component.

1. Unused Classes

Each component layer of the Button has a unused class name that can be utilized in your local CSS to customize the Button at any level.

1. pando-button: The element of the Button.

2. Passing a className prop

You can pass a className prop to the Button component to customize the Button. This is useful if your project uses CSS Modules or a CSS-in-JS library like Emotion.

import customStyles from './customStyles.module.css'

function CustomButton(props) {
  return <Button className={customStyles.customButton}>{props.children}</Button>
}

3. Ejected Button

For a low-level "ejected" approach, you can use the Headless-styles API to customize the Button however you prefer while keeping the accessibility behavior.

import {
  getButtonProps,
  getButtonIconOptions,
} from '@pluralsight/headless-styles'

To learn more about the Headless-styles API, check out the Headless-styles documentation.

Behavior

Patterns

Do use the Button for an actionable event needed from the user.

Don't use the Button for navigation or styled links. Instead use the TextLink component.

Do keep Button usage minimal within an area.

Don't use more than three Buttons in a single area.

Do space Buttons apart by 16px (1rem).

Don't space Buttons apart greater or less than 16px (1rem).

Sentiment

Do use the "action" sentiment for all use cases where possible.

Don't use the "default" sentiment unless it is a last resort.

Do use the "danger" sentiment for cancel or destructive actions.

Don't use the "default" sentiment for cancel or destructive actions.

Usage

Do use the "outline" usage for a lower priority alternative use case to the "default" sentiment.

Don't use the "outline" usage for cancel or destructive actions.

Do use the "text" usage for the lowest priority action.

Don't use the "text" usage as a high-priority action.

Sizing

Do use the default size for all use cases where possible of the Button.

Don't use the "m" size unless it is a last resort.

API

Parameters

interface ButtonOptions extends ButtonHTMLAttributes<HTMLButtonElement> {
  sentiment?: 'default' | 'action' | 'danger'
  usage?: 'filled' | 'outline' | 'text'
  size?: 'm' | 'l'
  endIcon?: ElementType
  startIcon?: ElementType
}

1. Any props that can be passed to an HTML button element.
2. sentiment - Determines the theme of the button. Defaults to action.
3. usage - Determines the visual style of the button. Defaults to filled.
4. size - Determines the size of the button. Defaults to l.
5. endIcon - Determines the icon to display at the end of the button.
6. startIcon - Determines the icon to display at the start of the button.

Size Mapping

{
  m: 'Use in condensed areas where the default size is too large.',
  l: 'Should be used in most, if not all cases.'
}

Accessibility

The Pando Button, and Icon APIs combined with semantic HTML allow the Button to be fully accessible and screen-readable by default.