Skip to main content

Icon Button

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

Anatomy

  1. Button
  2. Icon

Import

import { IconButton } from '@pluralsight/react'

Usage

Basic Buttons

function BasicIconButtons() {
  return (
    <Grid cols="repeat(12, 1fr)" gap={8}>
      <GridItem>
        <IconButton
          ariaLabel="action button"
          icon={PlaceholderIcon}
          sentiment="action"
        />
      </GridItem>

      <GridItem>
        <IconButton ariaLabel="default button" icon={PlaceholderIcon} />
      </GridItem>

      <GridItem>
        <IconButton
          ariaLabel="danger button"
          icon={PlaceholderIcon}
          sentiment="danger"
        />
      </GridItem>

      <GridItem>
        <IconButton
          ariaLabel="disabled button"
          disabled={true}
          icon={PlaceholderIcon}
          sentiment="default"
        />
      </GridItem>
    </Grid>
  )
}

Round Buttons

function RoundIconButtons() {
  return (
    <Grid cols="repeat(12, 1fr)" gap={8}>
      <GridItem>
        <IconButton
          ariaLabel="action round button"
          icon={PlaceholderIcon}
          sentiment="action"
          usage="round"
        />
      </GridItem>

      <GridItem>
        <IconButton
          ariaLabel="default round button"
          icon={PlaceholderIcon}
          usage="round"
        />
      </GridItem>

      <GridItem>
        <IconButton
          ariaLabel="danger round button"
          icon={PlaceholderIcon}
          sentiment="danger"
          usage="round"
        />
      </GridItem>
    </Grid>
  )
}

Text Buttons

function TextIconButtons() {
  return (
    <Grid cols="repeat(12, 1fr)" gap={8}>
      <GridItem>
        <IconButton
          ariaLabel="action text button"
          icon={PlaceholderIcon}
          sentiment="action"
          usage="text"
        />
      </GridItem>

      <GridItem>
        <IconButton
          ariaLabel="default text button"
          icon={PlaceholderIcon}
          sentiment="default"
          usage="text"
        />
      </GridItem>

      <GridItem>
        <IconButton
          ariaLabel="danger text button"
          icon={PlaceholderIcon}
          sentiment="danger"
          usage="text"
        />
      </GridItem>
    </Grid>
  )
}

Sizes

function BasicButtons() {
  return (
    <Grid cols="repeat(12, 1fr)" gap={8} data-site-override="alignGridCenter">
      <GridItem>
        <IconButton
          ariaLabel="action medium button"
          icon={PlaceholderIcon}
          sentiment="action"
          size="m"
        />
      </GridItem>

      <GridItem>
        <IconButton
          ariaLabel="default large button"
          icon={PlaceholderIcon}
          size="l"
        />
      </GridItem>
    </Grid>
  )
}

Customizing

There are 3 ways to customize the IconButton component.

1. Unused Classes

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

  1. pando-icon-button: The element of the IconButton.
  2. pando-icon: The element of the Icon.

2. Passing a className prop

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

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

function CustomIconButton(props) {
  return (
    <IconButton ariaLabel={props.ariaLabel} className={customStyles.custom}>
      {props.children}
    </IconButton>
  )
}

3. Ejected IconButton

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

import { getIconButtonProps } 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 IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  ariaLabel: string
  sentiment?: 'default' | 'action' | 'danger'
  usage?: 'square' | 'round' | 'text'
  size?: 'm' | 'l'
}
  1. ariaLabel: The aria-label attribute for the button.
  2. sentiment: The theme of the button. Defaults to "default".
  3. usage: The styling of the button. Defaults to "square".
  4. size: The size of the button. Defaults to "l".

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 IconButton is fully accessible and screen-readable through the following features:

  1. The aria-label attribute is added for the label element/version.
  2. The aria-hidden attribute is added for the icon element/version.

All other accessibility features are handled by the Button component natively.