Button - Nuxt UI

Usage

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

<UButton>Button</UButton>

You can also use the label prop.

label

<UButton label="Button" />

Style

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

color

variant

<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

variant

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

Gray

variant

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

Black

variant

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

Size

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

size

<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.

size

color

variant

trailing

<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.

size

color

variant

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

Disabled

Use the disabled prop to disable the Button.

disabled

<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.

block

<UButton block>Button</UButton>

Link

Use the to prop to make the Button a link.

target

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.

padded

<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.

square

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

Truncate

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

truncate

label

<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

size

orientation

<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:

size

orientation

<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.

label

<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.

label

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

Props

type

string

"button"

any

undefined

size

ButtonSize

config.default.size

"sm""2xs""xs""md""lg""xl"

color

string

config.default.color

variant

ButtonVariant

config.default.variant

"link""solid""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

boolean

false

padded

boolean

true

trailing

boolean

false

leading

boolean

false

truncate

boolean

false

ButtonGroup

any

undefined

size

ButtonSize

null

"sm""2xs""xs""md""lg""xl"

orientation

"horizontal" | "vertical"

"horizontal"

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.