Button

Importing

You can import the Button component via:

import { Button } from '@customerio/pluma-components/react';

Variants

Primary

Use a primary button as a CTA for the most important action on a page. Ideally, there should be at most only one primary button on any given page.

Secondary

A secondary button can be used for any action less important than "primary". There can be multiple secondary buttons on a page. This is the default, if no variant is provided.

Tertiary

A tertiary button can also be used for "secondary" actions, but with less visual weight attached to it.

Subtle

A subtle button is another low-priority button type, but without a border, to make it even less prominent than the "tertiary" or "secondary" styles.

Links with button styles

The Button component accepts a href prop, which makes it render an anchor element with the button component's styles. This link will behave like the Link component. This means:

• Button will use the provider's linkComponent (or an a tag for external links)
• Button will also accept PlainLink props, like isExternal or replace

For buttons that render just like a link (i.e. renders inline and doesn't include paddings), see the Link component.

Danger states

All button variations support an danger state via the isDanger argument. This should be used for "dangerous" actions, like deleting a model.

Note: isError is the deprecated name for this argument.

Size

A button can be medium (default) or small:

Icons

A button will render an icon if an icon name is passed in as the icon argument:

Icon position

The icon can be positioned on either side with the iconPosition argument, which can be either 'leading' or 'trailing'. 'leading' is the default, if no argument is provided.

Icon only button

A button can be rendered with just an icon by setting the isIconOnly argument to true. This will stop the button from rendering the text content, and adjust the paddings so it looks balanced:

Custom icons

If you need to use a custom icon that isn't part of the Pluma Icon set, you can use the iconSrc prop to provide a URL to an image. The image will be automatically sized to match the button's icon size:

Custom image icons support the same positioning options as standard icons:

When both icon and iconSrc are provided, iconSrc takes precedence. If iconSrc is an empty string, the component will fall back to using the icon prop.

Two icons at once

iconLeading and iconTrailing are shortcuts for a fixed side, so a button can carry an icon on each side. They render in addition to icon rather than replacing it, so an existing icon/iconPosition pair keeps working alongside them.

Custom elements

Use elementBefore and elementAfter for trailing or leading content that isn't an icon — a count badge, for example. elementBefore renders between any leading icon and the label; elementAfter renders between the label and any trailing icon. Both compose with the icons rather than replacing them, and the button's own content spacing applies to them.

In React, both are node props. In Ember, they can be passed as a component or, more commonly, via the :elementBefore and :elementAfter named blocks (the label is then provided via the :default block).

Disabled buttons

Whenever possible, we prefer using native HTML attributes over custom component arguments. In this component's case, there is an exception for the disabled attribute.

Use the isDisabled argument instead of the native disabled attribute. Rather than setting the native disabled attribute, the Button renders aria-disabled="true" and blocks click events. This is deliberate: a natively disabled element is removed from the accessibility tree and the tab order, so screen readers skip it and it can't be focused — which breaks tooltips and other affordances that explain why the button is disabled. Using aria-disabled keeps the button focusable and announced (as disabled) while still preventing interaction.

It also works around a second limitation: the disabled attribute isn't valid on all HTML elements, so we can't rely on the browser to universally render the disabled style or block clicks — important when the Button renders as a link (for example, a routing-library link we want to disable).

Loading states

Buttons are often tied to some sort of asynchronous task like saving data to the server, polling for updates, etc. In those cases, it's a good idea to signal to the user that the UI is not frozen and something is happening behind the scenes.

To show a spinner during an asynchronous action, pass the isLoading argument to a Button. The original button text will be retained so that the button doesn't change shape. Additionally, the button will be disabled so that the user can't click the button again.

Because this scenario is so common, you have the option to pass a function that returns a promise to the onClick argument. This will automatically show the spinner while the promise is running. If you want to pass a promise to onClick, but don't want the spinner to display, you can set the autoLoading argument to false.