Button

They provide clear visual feedback and communicate the importance and intent of an action.

The Puzzle Button component supports both native buttons and links. When a href is provided, the component automatically renders a Puzzle Link instead of a native <button>.

Read more about the Link component here.

ImportCopy Anchor Link

import { Button } from "@puzzle-ui/ui";

Basic usageCopy Anchor Link

Use the Button component to trigger an action.

By default, a Button renders a native HTML <button> element with type="button".

VariantsCopy Anchor Link

The variant prop controls the visual appearance and emphasis of the Button.

The default variant is primary.

The link variant only changes the visual appearance. It does not turn the Button into a navigation link. To render an actual link, provide an href.

SizesCopy Anchor Link

Use the size prop to control the dimensions of the Button.

The default size is md.

The icon size is intended for buttons that contain only an icon. Always provide an accessible name, for example through aria-label.

Leading and trailing contentCopy Anchor Link

The leading and trailing props allow you to add content before or after the Button's children.

They are useful for icons, indicators, or other supplementary content.

Both props accept React nodes, so you can use any component or element as their content.

When loading is enabled, the leading content is replaced by the loading indicator. Trailing content remains visible.

LoadingCopy Anchor Link

Use the loading prop to indicate that an action is being processed.

When loading:

• A loading indicator replaces the leading content.
• The Button receives aria-busy="true".
• Native buttons become disabled.
• Link buttons prevent navigation and interaction.
• Trailing content remains visible.

The loading state also prevents accidental repeated activation while an operation is in progress.

DisabledCopy Anchor Link

Use the disabled prop when an action is currently unavailable.

The disabled state can also be activated through aria-disabled.

For native buttons, the component uses the native disabled attribute.

For links, the component uses aria-disabled, removes the link from the tab order, and prevents mouse and keyboard activation. This preserves the semantic distinction between a button and a link while providing consistent disabled behavior.

A Button is also considered disabled while loading is active.

Full widthCopy Anchor Link

Use fullWidth to make a Button fill the available width of its container.

This is useful for form actions, mobile layouts, and other situations where a full-width action is preferred.

Navigation linksCopy Anchor Link

The Button component automatically renders a Puzzle Link when an href is provided.

This means you can use the same component API for actions and navigation without manually switching between Button and Link components.

The component determines which element to render based on the presence of href:

The href property is required when using the link version of the Button.

Router-specific propertiesCopy Anchor Link

The link version supports the properties of the Puzzle Link component.

Router-specific properties can be passed through componentProps.

<Button
  href="/dashboard"
  componentProps={
    {
      // Router-specific properties
    }
  }
>
  Go to dashboard
</Button>

This allows the Button to work with the routing integrations supported by Puzzle without coupling the Button component to a specific router.

Link versus buttonCopy Anchor Link

Use a native Button when the user is performing an action, such as submitting a form, opening a dialog, or saving data.

Use href when the user is navigating to another location.

The visual link variant does not change the underlying HTML element. Navigation semantics are determined by href, not by variant.

APICopy Anchor Link

PropsCopy Anchor Link

The Button component exposes a shared set of properties for both native buttons and links.

Native button propsCopy Anchor Link

When href is not provided, the component renders a native HTML <button>.

All standard React button attributes are supported, including:

• type
• onClick
• onFocus
• onBlur
• name
• value
• form
• aria-\*
• data-\*

The type property defaults to "button".

Link propsCopy Anchor Link

When href is provided, the component renders a Puzzle Link.

The link version supports the properties of the Puzzle Link component, including:

• href
• target
• rel
• onClick
• aria-*
• data-*
• componentProps

The href property is required for this version.

TypeScript typesCopy Anchor Link

The component exposes the following types:

type ButtonVariant =
  | "primary"
  | "secondary"
  | "outline"
  | "ghost"
  | "danger"
  | "link"
  | "toggle"
  | "toggle-active";

type ButtonSize = "xs" | "sm" | "md" | "lg" | "icon";

type ButtonProps = ButtonNativeProps | ButtonLinkProps;

ButtonProps is a discriminated union based on the presence of href.

This ensures that native button attributes and link attributes are correctly typed and that incompatible properties cannot accidentally be combined.

For example, type is only available on the native button version, while href is required for the link version.

AccessibilityCopy Anchor Link

The Button component includes accessibility behavior for both native buttons and links.

Keyboard interactionCopy Anchor Link

• Native buttons support the standard browser keyboard interactions.
• Link buttons support normal link keyboard navigation.
• Disabled links cannot be activated using Enter or Space.
• Disabled links are removed from the tab order.

Focus visibilityCopy Anchor Link

Buttons provide a visible focus indicator when navigating with a keyboard through :focus-visible.

Loading stateCopy Anchor Link

When loading:

• The component exposes aria-busy="true".
• The loading indicator is hidden from assistive technology.
• The Button cannot be activated again until loading ends.

Disabled stateCopy Anchor Link

The component uses the native disabled attribute for buttons and aria-disabled for links.

This ensures that the underlying element retains the correct semantic meaning.

Icon-only buttonsCopy Anchor Link

When using size="icon", always provide an accessible name.

Do not rely on the visual appearance of an icon to communicate its meaning to assistive technology.

Reduced motionCopy Anchor Link

The Button respects the user's reduced-motion preference. Transitions and loading animations are adjusted when prefers-reduced-motion: reduce is active.