Elements

Button

GitHub

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">Button</UButton>

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">Button</UButton>

Gray

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

Black

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

Size

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

<UButton size="sm">Button</UButton>

Rounded

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

<UButton :ui="{ rounded: 'rounded-full' }">Button</UButton>
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>Button</UButton>

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>Button</UButton>

Block

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

<UButton block>Button</UButton>

Link

Use the to prop to make the Button a link.

Button

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

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"
  color="gray"
  variant="link"
  icon="i-heroicons-x-mark-20-solid"
/>

Square

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

<UButton square label="Button" color="gray" variant="solid" />

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>

This can also work with an Input component for example:

<UButtonGroup size="sm" orientation="horizontal">
  <UInput />
  <UButton icon="i-heroicons-clipboard-document" 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
string
config.default.color
variant
ButtonVariant
config.default.variant
"solid""link""outline""soft""ghost"
icon
string
null
label
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
ButtonGroup
size
"sm" | "2xs" | "xs" | "md" | "lg" | "xl"
null
orientation
"horizontal" | "vertical"
"horizontal"
ui
any
undefined

Config

{
  "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"
  }
}

{
  "wrapper": {
    "horizontal": "inline-flex -space-x-px",
    "vertical": "inline-flex flex-col -space-y-px"
  },
  "rounded": "rounded-md",
  "shadow": "shadow-sm"
}

Badge

Display a short text to represent a status or a category.

Dropdown

Display a list of actions in a dropdown menu.