Skip to main content
Bedrock Design System

IconButton

Buttons are used to trigger actions. The label of the button expresses clearly to the user what that action is and what will happen when the button is pressed.

AnatomyPermalink to: Anatomy

  1. Container: Houses the contents of the Icon Button. Visual appearance differs based on button type.
  2. Shape: Icon Button can either be circular or square with rounded corners.
  3. Icon: Visual indicator. Make sure that the icon is discernible.

UsagePermalink to: Usage

The Icon Button offers the opportunity to have a button element without a visible text label. Use with caution, as 24x24 icons can be tricky to decode and not all icons are universally understood. Make sure that the icon is discernible, and consider using a tooltip with the Icon Button to help explain ambiguous icons for everyone.

When to usePermalink to: When to use

  • Inside modules where space is scarce.
  • On pages where a module might be repeated a number of times, resulting in buttons with visible text labels being too verbose.

When not to usePermalink to: When not to use

  • If it is at all feasible to use a text button, use Button. Remember that Button also allows for an icon, but with the added clarity of text.

AccessibilityPermalink to: Accessibility

Even if the Icon Button does not have a visible text label, it does have a hidden one which is exposed to assistive technologies such as screen readers.

ExamplesPermalink to: Examples

VariantsPermalink to: Variants

When deciding which Icon Button to use, consider its level of priority and how much visual emphasis it should have on the page. Refer to the examples below to determine which is right for your use case:

VariantDescription
PrimaryUse for the principal, positive call to action. Submitting forms, saving changes, etc. Avoid having multiple primary buttons next to each other or stacked, as they are styled to attract attention, and will clump. Choose a primary action, and use secondary for the remaining options.
SecondaryA more discreet Button for secondary actions like ‘Cancel’, ‘Edit’ and other non-primary choices.
TertiaryFor use on less important, prominent actions. They can be used in isolation or paired with a primary or secondary Button when there are multiple actions.
WarningUse for negative but non-destructive actions. They work in stacked lists.
DangerOnly to be used if doing a very destructive, irreversible action, such as deleting a company. Avoid using in stacked lists, as the red styling is very heavy.
Open
import { IconButton } from "@peakon/bedrock/react/button";
import { Inline } from "@peakon/bedrock/react/layout";
import { SystemIcon } from "@peakon/bedrock/react/assets/SystemIcon";

function Snippet() {
  return (
    <Inline spacing={8}>
      <IconButton
        variant="primary"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="primary"
      />
      <IconButton
        variant="secondary"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="secondary"
      />
      <IconButton
        variant="tertiary"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="tertiary"
      />
      <IconButton
        variant="warning"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="warning"
      />
      <IconButton
        variant="danger"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="danger"
      />
    </Inline>
  );
}

SizesPermalink to: Sizes

Icon Button support four sizes: xsmall, small, medium (default) and large. Which is appropriate will depend on the size of its surrounding elements and visual space.

Open
import { IconButton } from "@peakon/bedrock/react/button";
import { Inline } from "@peakon/bedrock/react/layout";
import { SystemIcon } from "@peakon/bedrock/react/assets/SystemIcon";

function Snippet() {
  return (
    <Inline spacing={8}>
      <IconButton
        variant="primary"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        size="xsmall"
        accessibleName="xsmall"
      />
      <IconButton
        variant="primary"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        size="small"
        accessibleName="small"
      />
      <IconButton
        variant="primary"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        size="medium"
        accessibleName="medium"
      />
      <IconButton
        variant="primary"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        size="large"
        accessibleName="large"
      />
    </Inline>
  );
}

RoundedPermalink to: Rounded

If more compatible with the design, the Icon Button can be rounded.

Open
import { IconButton } from "@peakon/bedrock/react/button";
import { Inline } from "@peakon/bedrock/react/layout";
import { SystemIcon } from "@peakon/bedrock/react/assets/SystemIcon";

function Snippet() {
  return (
    <Inline spacing={8}>
      <IconButton
        variant="primary"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="primary"
        rounded
      />
      <IconButton
        variant="secondary"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="secondary"
        rounded
      />
      <IconButton
        variant="tertiary"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="tertiary"
        rounded
      />
      <IconButton
        variant="warning"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="warning"
        rounded
      />
      <IconButton
        variant="danger"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="danger"
        rounded
      />
    </Inline>
  );
}

Sometimes it may be necessary to use a link that looks like an Icon Button, which is supported for both native <a> elements and framework-specific elements, such as React Router's Link(external link) or Next.js' Link(external link) components. This usage pattern should be the exception rather than the rule.

Open
import { LinkIconButton } from "@peakon/bedrock/react/button";
import { Inline } from "@peakon/bedrock/react/layout";
import { SystemIcon } from "@peakon/bedrock/react/assets/SystemIcon";
import { default as NextLink } from "next/link";

function Snippet() {
  return (
    <Inline spacing={8}>
      <LinkIconButton
        variant="primary"
        as="a"
        href="https://app.peakon.com"
        accessibleName="Next"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
      />
      <LinkIconButton
        variant="secondary"
        as={NextLink}
        href="https://app.peakon.com"
        accessibleName="Next"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
      />
    </Inline>
  );
}

Busy statePermalink to: Busy state

The Icon Button can be set to a busy state, which is useful when the Icon Button is used to trigger an action that takes some time to complete.

The busy state is indicated by a spinner, and the Icon Button will be announced as busy for assistive technology, while the action is being performed.

It's up the the consumer to chose when or when not to use the busy state. A good rule of thumb is to use it, when you know an action will take a considerable amount of time to complete, eg. generating a file for download. If you are unsure whether an action will take a long time or not to complete, consider adding a small delay before setting the IconButton to busy - this way it will only show, if the actions takes a considerable amount of time.

Open
import { IconButton } from "@peakon/bedrock/react/button";
import { Inline } from "@peakon/bedrock/react/layout";
import { SystemIcon } from "@peakon/bedrock/react/assets/SystemIcon";

function Snippet() {
  return (
    <Inline spacing={8}>
      <IconButton
        variant="primary"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="primary"
        busy
      />
      <IconButton
        variant="secondary"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="secondary"
        busy
      />
      <IconButton
        variant="tertiary"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="tertiary"
        busy
      />
      <IconButton
        variant="warning"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="warning"
        busy
      />
      <IconButton
        variant="danger"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="danger"
        busy
      />
    </Inline>
  );
}

TooltipPermalink to: Tooltip

Enable the tooltip with the withTooltip prop. Uses the accessibleName for the label.

Open
import { IconButton } from "@peakon/bedrock/react/button";
import { Inline } from "@peakon/bedrock/react/layout";
import { SystemIcon } from "@peakon/bedrock/react/assets/SystemIcon";

function Snippet() {
  return (
    <Inline spacing={8}>
      <IconButton
        variant="primary"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="primary"
        withTooltip
      />
      <IconButton
        variant="secondary"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="secondary"
        withTooltip
      />
      <IconButton
        variant="tertiary"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="tertiary"
        withTooltip
      />
      <IconButton
        variant="warning"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="warning"
        withTooltip
      />
      <IconButton
        variant="danger"
        icon={<SystemIcon name="navigation-basic-navigation-chevron-right" />}
        accessibleName="danger"
        withTooltip
      />
    </Inline>
  );
}

Props TablePermalink to: Props Table

IconButtonPermalink to: IconButton

Props extend from HTML Button Element(external link), with the omission of className and style

NameTypeDescriptionDefaultRequired
refHTMLButtonElement

Forwards a ref to the IconButton.

—No
accessibleNamestring

Provides a label for the IconButton that is visible to assistive technologies.

falseNo
sizexsmall | small | medium | large

Defines the size of the IconButton.

mediumNo
variantprimary | secondary | tertiary | warning | danger

Defines the variant of the IconButton.

—Yes
iconReactNode

Defines what icon to render in the IconButton (Peakon system icon recommended)

—No
withTooltipboolean

Enabled the tooltip for the IconButton.

falseNo
busyboolean

Set the busy prop to indicate that the IconButton is working and not currently intractable. Setting busy suppresses the click event, renders a spinner for visual feedback, and semantically indicates that it is disabled, but retains keyboard focus.

falseNo

LinkIconButtonPermalink to: LinkIconButton

Props extend from HTML anchor element(external link), with the omission of className and style

NameTypeDescriptionDefaultRequired
refHTMLAnchorElement

Forwards a ref to the LinkIconButton.

—No
asElementType

The LinkIconButton also supports custom link components via the as prop, from eg. Next or React Router.

aNo
accessibleNamestring

Provides a label for the IconButton that is visible to assistive technologies.

falseNo
sizexsmall | small | medium | large

Defines the size of the LinkIconButton.

mediumNo
variantprimary | secondary | tertiary | warning | danger

Defines the variant of the LinkIconButton.

—Yes
iconReactNode

Defines what icon to render in the LinkIconButton (Peakon system icon recommended)

—No
withTooltipboolean

Enabled the tooltip for the IconButton.

falseNo
busyboolean

Set the busy prop to indicate that the LinkButton is working and not currently intractable. Setting busy suppresses the click event, renders a spinner for visual feedback, and semantically indicates that it is disabled, but retains keyboard focus.

falseNo