Button

Enables users to trigger an action or event, such as submitting a form, opening a dialog, canceling an action, or performing a delete operation.

Import

tsx
import { Button, IconButton, LinkButton, LinkIconButton } from "@kobalte/pigment";

tsx
import { Button, IconButton, LinkButton, LinkIconButton } from "@kobalte/pigment";

Basic usage

tsx
<Button>New pull request</Button>

tsx
<Button>New pull request</Button>

Customization

Variants

Buttons comes in multiple variants designed for specific use cases.

Primary

The solid button variant with primary color is best suited for the most important action within an interface.

tsx
<Button variant="solid" color="primary">
  Create survey
</Button>

tsx
<Button variant="solid" color="primary">
  Create survey
</Button>

The soft button variant with primary color can be used as an alternative for secondary actions.

tsx
<Button variant="soft" color="primary">
  Export results
</Button>

tsx
<Button variant="soft" color="primary">
  Export results
</Button>

Destructive

Use the solid or soft variant with the danger color to create a destructive button, commonly used to confirm a destructive/delete operation.

tsx
<Button variant="solid" color="danger">
  Delete survey
</Button>
<Button variant="soft" color="danger">
  Remove answer
</Button>

tsx
<Button variant="solid" color="danger">
  Delete survey
</Button>
<Button variant="soft" color="danger">
  Remove answer
</Button>

Default

The default variant is the most common button within an interface, use it for secondary actions or when all actions have the same level of importance.

tsx
<Button>Copy</Button>
// Or
<Button variant="default">Export</Button>

tsx
<Button>Copy</Button>
// Or
<Button variant="default">Export</Button>

Dashed

The dashed variant can be used as a visual placeholder for insertion/creation actions.

tsx
<Button variant="dashed" leadingIcon={<AddIcon />}>
  Add new row
</Button>

tsx
<Button variant="dashed" leadingIcon={<AddIcon />}>
  Add new row
</Button>

Text

text buttons are designed for least important actions within an interface.

tsx
<Button variant="text">Cancel</Button>

tsx
<Button variant="text">Cancel</Button>

Link

The link variant is used to render a button that looks like a link.

tsx
<Button variant="link">Show more</Button>

tsx
<Button variant="link">Show more</Button>

Inverted

The inverted variant supports all Pigment semantic colors and can be used to create a high contrast button on a vibrant surface of the same color|status.

tsx
<Alert
  variant="solid"
  status="info"
  trailingSection={
    <Button variant="inverted" color="info" size="sm">
      Install now
    </Button>
  }
>
  <span class="font-semibold">New software update available.</span>
</Alert>

tsx
<Alert
  variant="solid"
  status="info"
  trailingSection={
    <Button variant="inverted" color="info" size="sm">
      Install now
    </Button>
  }
>
  <span class="font-semibold">New software update available.</span>
</Alert>

Status buttons

The solid and soft variant supports all Pigment semantic colors, allowing you to create status buttons.

tsx
<For each={["solid", "soft"]}>
  {variant => (
    <div class="flex items-center gap-3">
      <For each={["primary", "success", "info", "warning", "danger", "discovery"]}>
        {color => (
          <Button variant={variant} color={color} class="capitalize">
            {color}
          </Button>
        )}
      </For>
    </div>
  )}
</For>

tsx
<For each={["solid", "soft"]}>
  {variant => (
    <div class="flex items-center gap-3">
      <For each={["primary", "success", "info", "warning", "danger", "discovery"]}>
        {color => (
          <Button variant={variant} color={color} class="capitalize">
            {color}
          </Button>
        )}
      </For>
    </div>
  )}
</For>

These buttons works well when paired with others status-related components like Alert or Badge.

tsx
<Alert
  variant="soft"
  status="discovery"
  trailingSection={
    <div class="flex items-center gap-2.5">
      <Button variant="soft" color="discovery" size="sm">
        Skip
      </Button>
      <Button variant="solid" color="discovery" size="sm">
        Take a tour
      </Button>
    </div>
  }
>
  <span class="font-semibold">Learn about the latest features.</span>
</Alert>

tsx
<Alert
  variant="soft"
  status="discovery"
  trailingSection={
    <div class="flex items-center gap-2.5">
      <Button variant="soft" color="discovery" size="sm">
        Skip
      </Button>
      <Button variant="solid" color="discovery" size="sm">
        Take a tour
      </Button>
    </div>
  }
>
  <span class="font-semibold">Learn about the latest features.</span>
</Alert>

Sizes

The Button component comes in five sizes: xs, sm, md (default), lg and xl.

tsx
<Button size="xs">Button</Button>
<Button size="sm">Button</Button>
<Button size="md">Button</Button>
<Button size="lg">Button</Button>
<Button size="xl">Button</Button>

tsx
<Button size="xs">Button</Button>
<Button size="sm">Button</Button>
<Button size="md">Button</Button>
<Button size="lg">Button</Button>
<Button size="xl">Button</Button>

Icons

Use the leadingIcon and trailingIcon props to append icons to either side of the button.

tsx
<Button leadingIcon={<ClipboardIcon />}>Copy to clipboard</Button>
<Button trailingIcon={<ArrowNarrowRightIcon />}>Next</Button>

tsx
<Button leadingIcon={<ClipboardIcon />}>Copy to clipboard</Button>
<Button trailingIcon={<ArrowNarrowRightIcon />}>Next</Button>

If you want to create your own icon components check out the Icon documentation.

Full width

Use the fullWith prop to make the button fill all available width.

tsx
<Button fullWidth>Create Survey</Button>

tsx
<Button fullWidth>Create Survey</Button>

Disabled state

Use the disabled prop to disable interaction with the button.

tsx
<Button variant="solid" disabled>Solid</Button>
<Button variant="soft" disabled>Soft</Button>
<Button variant="default" disabled>Default</Button>
<Button variant="dashed" disabled>Dashed</Button>
<Button variant="text" disabled>Text</Button>
<Button variant="link" disabled>Link</Button>

tsx
<Button variant="solid" disabled>Solid</Button>
<Button variant="soft" disabled>Soft</Button>
<Button variant="default" disabled>Default</Button>
<Button variant="dashed" disabled>Dashed</Button>
<Button variant="text" disabled>Text</Button>
<Button variant="link" disabled>Link</Button>

Loading state

Use the loading prop to indicate a busy button.

tsx
<Button variant="solid" loading>Solid</Button>
<Button variant="soft" loading>Soft</Button>
<Button variant="default" loading>Default</Button>
<Button variant="dashed" loading>Dashed</Button>
<Button variant="text" loading>Text</Button>
<Button variant="link" loading>Link</Button>

tsx
<Button variant="solid" loading>Solid</Button>
<Button variant="soft" loading>Soft</Button>
<Button variant="default" loading>Default</Button>
<Button variant="dashed" loading>Dashed</Button>
<Button variant="text" loading>Text</Button>
<Button variant="link" loading>Link</Button>

Loading icon

By default, a loading button show a spinner and leave the button's width unchanged. Use the loadingIcon prop to replace it with a custom icon.

tsx
<Button loading loadingIcon={<BeatLoaderIcon />}>
  Export results
</Button>

tsx
<Button loading loadingIcon={<BeatLoaderIcon />}>
  Export results
</Button>

Loading placement

The loadingPlacement prop is used to define the placement of the button's loading icon and supports the following values:

• center (default): The loading icon replaces the button's content when in the loading state.
• leading: The loading icon replaces the leadingIcon when in the loading state.
• trailing: The loading icon replaces the trailingIcon when in the loading state.

tsx
<Button loading loadingPlacement="leading">
  Export results
</Button>
<Button variant="solid" loading loadingPlacement="trailing">
  Create survey
</Button>

tsx
<Button loading loadingPlacement="leading">
  Export results
</Button>
<Button variant="solid" loading loadingPlacement="trailing">
  Create survey
</Button>

IconButton

The IconButton component renders a square button with an icon and no text content. In this case an aria-label is required to keep the button accessible.

tsx
<IconButton aria-label="Delete">
  <TrashIcon />
</IconButton>

tsx
<IconButton aria-label="Delete">
  <TrashIcon />
</IconButton>

LinkButton

Use the LinkButton or LinkIconButton if you need the style of a button with the functionality of a link.

tsx
<LinkButton href="https://github.com/kobaltedev/pigment" target="_blank">
  Open on GitHub
</LinkButton>
<LinkIconButton
  href="https://github.com/kobaltedev/pigment"
  target="_blank"
  aria-label="Open on GitHub"
>
  <GitHubIcon />
</LinkIconButton>

tsx
<LinkButton href="https://github.com/kobaltedev/pigment" target="_blank">
  Open on GitHub
</LinkButton>
<LinkIconButton
  href="https://github.com/kobaltedev/pigment"
  target="_blank"
  aria-label="Open on GitHub"
>
  <GitHubIcon />
</LinkIconButton>

If you want to use the Link component from the @solidjs/router package, use the asChild prop paired with the As component to change the rendered element.

tsx
<LinkButton asChild>
  <As component={Link} href="/" target="_blank">
    Back to home
  </As>
</LinkButton>

tsx
<LinkButton asChild>
  <As component={Link} href="/" target="_blank">
    Back to home
  </As>
</LinkButton>

API Reference

Button

Component identifier

The name Button can be used when providing default props and slot classes in the theme.

Props

Slots

IconButton

Component identifier

IconButton uses the Button theme configuration.

Props

Slots

LinkButton

Component identifier

The name LinkButton can be used when providing default props and slot classes in the theme.

Props

Slots

LinkIconButton

Component identifier

LinkIconButton uses the LinkButton theme configuration.

Props

Slots