elements

Button

Create a button with icon or link capabilities.

Usage

Use the default slot to set the text of the Button.

<UButton>Button</UButton>

You can also use the label prop.

<UButton label="Button" />

Style

Use the color and variant props to change the visual style of the Button.

<UButton color="primary" variant="solid" />

Besides all the colors from the ui.colors object, you can also use the white, gray and black colors with their pre-defined variants.

White

<UButton color="white" variant="solid" />

Gray

<UButton color="gray" variant="solid" />

Black

<UButton color="black" variant="solid" />

Size

Use the size prop to change the size of the Button.

<UButton size="sm" />

Rounded

To customize the border radius of the Button, you can use the ui prop.

<UButton :ui="{ rounded: 'rounded-full' }" />
You can customize the whole preset by using the ui prop.

Icon

Use any icon from Iconify by setting the icon prop by using this pattern: i-{collection_name}-{icon_name}.

Use the leading and trailing props to set the icon position or the leading-icon and trailing-icon props to set a different icon for each position.

<UButton icon="i-heroicons-pencil-square" size="sm" color="primary" variant="solid" label="Button" :trailing="false" />

The label as prop or slot is optional so you can use the Button as an icon-only button.

<UButton icon="i-heroicons-pencil-square" size="sm" color="primary" square variant="solid" />

Disabled

Use the disabled prop to disable the Button.

<UButton disabled />

Loading

Use the loading prop to show a loading icon and disable the Button.

Use the loading-icon prop to set a different icon or change it globally in ui.button.default.loadingIcon. Defaults to i-heroicons-arrow-path-20-solid.

<UButton loading />

Block

Use the block prop to make the Button fill the width of its container.

<UButton block />

Use the to prop to make the Button a link.

<UButton to="https://volta.net" target="_blank" />

You can also pass any property from the NuxtLink component such as target, exact, etc.

Padded

Use the padded prop to remove the padding of the Button.

<UButton :padded="false" />

Square

Use the square prop to force the Button to have the same padding horizontally and vertically.

<UButton square />

Truncate

Use the truncate prop to truncate the label of the Button.

<UButton truncate class="w-20" label="Button with a long text" />

Group

To stack buttons as a group, use the ButtonGroup component.

  • To size all the buttons equally, pass the size prop
  • To change the orientation of the buttons, set the orientation prop to vertical
  • To adjust the rounded or the shadow around buttons, customize with ui.buttonGroup.rounded or ui.buttonGroup.shadow
<UButtonGroup size="sm" orientation="horizontal">
  <UButton label="Action" color="white" />
  <UButton icon="i-heroicons-chevron-down-20-solid" color="gray" />
</UButtonGroup>

Slots

leading

Use the #leading slot to set the content of the leading icon.

<UButton label="Button" color="gray">
  <template #leading>
    <UAvatar src="https://avatars.githubusercontent.com/u/739984?v=4" size="3xs" />
  </template>
</UButton>

trailing

Use the #trailing slot to set the content of the trailing icon.

<UButton label="Button" color="gray">
  <template #trailing>
    <UIcon name="i-heroicons-arrow-right-20-solid" />
  </template>
</UButton>

Props

size
"sm" | "2xs" | "xs" | "md" | "lg" | "xl"

config.default.size

ui
any

undefined

type
string

"button"

color
any

config.default.color

variant
ButtonVariant

config.default.variant

"link""solid""outline""soft""ghost"

label
string

null

icon
string

null

loadingIcon
string

config.default.loadingIcon

leadingIcon
string

null

trailingIcon
string

null

disabled
boolean

false

square
boolean

false

block
boolean

false

loading
boolean

false

padded
boolean

true

trailing
boolean

false

leading
boolean

false

truncate
boolean

false

Preset

{
  "base": "focus:outline-none focus-visible:outline-0 disabled:cursor-not-allowed disabled:opacity-75 flex-shrink-0",
  "font": "font-medium",
  "rounded": "rounded-md",
  "size": {
    "2xs": "text-xs",
    "xs": "text-xs",
    "sm": "text-sm",
    "md": "text-sm",
    "lg": "text-sm",
    "xl": "text-base"
  },
  "gap": {
    "2xs": "gap-x-1",
    "xs": "gap-x-1.5",
    "sm": "gap-x-1.5",
    "md": "gap-x-2",
    "lg": "gap-x-2.5",
    "xl": "gap-x-2.5"
  },
  "padding": {
    "2xs": "px-2 py-1",
    "xs": "px-2.5 py-1.5",
    "sm": "px-2.5 py-1.5",
    "md": "px-3 py-2",
    "lg": "px-3.5 py-2.5",
    "xl": "px-3.5 py-2.5"
  },
  "square": {
    "2xs": "p-1",
    "xs": "p-1.5",
    "sm": "p-1.5",
    "md": "p-2",
    "lg": "p-2.5",
    "xl": "p-2.5"
  },
  "color": {
    "white": {
      "solid": "shadow-sm ring-1 ring-inset ring-gray-300 dark:ring-gray-700 text-gray-900 dark:text-white bg-white hover:bg-gray-50 disabled:bg-white dark:bg-gray-900 dark:hover:bg-gray-800/50 dark:disabled:bg-gray-900 focus-visible:ring-2 focus-visible:ring-primary-500 dark:focus-visible:ring-primary-400",
      "ghost": "text-gray-900 dark:text-white hover:bg-white dark:hover:bg-gray-900 focus-visible:ring-inset focus-visible:ring-2 focus-visible:ring-primary-500 dark:focus-visible:ring-primary-400"
    },
    "gray": {
      "solid": "shadow-sm ring-1 ring-inset ring-gray-300 dark:ring-gray-700 text-gray-700 dark:text-gray-200 bg-gray-50 hover:bg-gray-100 disabled:bg-gray-50 dark:bg-gray-800 dark:hover:bg-gray-700/50 dark:disabled:bg-gray-800 focus-visible:ring-2 focus-visible:ring-primary-500 dark:focus-visible:ring-primary-400",
      "ghost": "text-gray-700 dark:text-gray-200 hover:text-gray-900 dark:hover:text-white hover:bg-gray-50 dark:hover:bg-gray-800 focus-visible:ring-inset focus-visible:ring-2 focus-visible:ring-primary-500 dark:focus-visible:ring-primary-400",
      "link": "text-gray-500 dark:text-gray-400 hover:text-gray-700 dark:hover:text-gray-200 underline-offset-4 hover:underline focus-visible:ring-inset focus-visible:ring-2 focus-visible:ring-primary-500 dark:focus-visible:ring-primary-400"
    },
    "black": {
      "solid": "shadow-sm text-white dark:text-gray-900 bg-gray-900 hover:bg-gray-800 disabled:bg-gray-900 dark:bg-white dark:hover:bg-gray-100 dark:disabled:bg-white focus-visible:ring-inset focus-visible:ring-2 focus-visible:ring-primary-500 dark:focus-visible:ring-primary-400",
      "link": "text-gray-900 dark:text-white underline-offset-4 hover:underline focus-visible:ring-inset focus-visible:ring-2 focus-visible:ring-primary-500 dark:focus-visible:ring-primary-400"
    }
  },
  "variant": {
    "solid": "shadow-sm text-white dark:text-gray-900 bg-{color}-500 hover:bg-{color}-600 disabled:bg-{color}-500 dark:bg-{color}-400 dark:hover:bg-{color}-500 dark:disabled:bg-{color}-400 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-{color}-500 dark:focus-visible:outline-{color}-400",
    "outline": "ring-1 ring-inset ring-current text-{color}-500 dark:text-{color}-400 hover:bg-{color}-50 disabled:bg-transparent dark:hover:bg-{color}-950 dark:disabled:bg-transparent focus-visible:ring-2 focus-visible:ring-{color}-500 dark:focus-visible:ring-{color}-400",
    "soft": "text-{color}-500 dark:text-{color}-400 bg-{color}-50 hover:bg-{color}-100 disabled:bg-{color}-50 dark:bg-{color}-950 dark:hover:bg-{color}-900 dark:disabled:bg-{color}-950 focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-{color}-500 dark:focus-visible:ring-{color}-400",
    "ghost": "text-{color}-500 dark:text-{color}-400 hover:bg-{color}-50 disabled:bg-transparent dark:hover:bg-{color}-950 dark:disabled:bg-transparent focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-{color}-500 dark:focus-visible:ring-{color}-400",
    "link": "text-{color}-500 hover:text-{color}-600 disabled:text-{color}-500 dark:text-{color}-400 dark:hover:text-{color}-500 dark:disabled:text-{color}-400 underline-offset-4 hover:underline focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-{color}-500 dark:focus-visible:ring-{color}-400"
  },
  "icon": {
    "base": "flex-shrink-0",
    "size": {
      "2xs": "h-4 w-4",
      "xs": "h-4 w-4",
      "sm": "h-5 w-5",
      "md": "h-5 w-5",
      "lg": "h-5 w-5",
      "xl": "h-6 w-6"
    }
  },
  "default": {
    "size": "sm",
    "variant": "solid",
    "color": "primary",
    "loadingIcon": "i-heroicons-arrow-path-20-solid"
  }
}