Components

Button

GitHub
Create a button with icon or link capabilities.

Usage

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

<template>
  <UButton>Button</UButton>
</template>

You can also use the label prop.

<template>
  <UButton label="Button" />
</template>

Style

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

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

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

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

Gray

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

Black

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

Size

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

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

Rounded

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

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

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

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

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

Disabled

Use the disabled prop to disable the Button.

<template>
  <UButton disabled>Button</UButton>
</template>

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.

<template>
  <UButton loading>Button</UButton>
</template>

Block

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

<template>
  <UButton block>Button</UButton>
</template>

Link

Use the to prop to make the Button a link.

Button

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

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.

<template>
  <UButton
    :padded="false"
    color="gray"
    variant="link"
    icon="i-heroicons-x-mark-20-solid"
  />
</template>

Square

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

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

Truncate

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

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

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
<template>
  <UButtonGroup size="sm" orientation="horizontal">
    <UButton label="Action" color="white" />
    <UButton icon="i-heroicons-chevron-down-20-solid" color="gray" />
  </UButtonGroup>
</template>

This can also work with an Input component for example:

<template>
  <UButtonGroup size="sm" orientation="horizontal">
    <UInput />
    <UButton icon="i-heroicons-clipboard-document" color="gray" />
  </UButtonGroup>
</template>

Slots

leading

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

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

trailing

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

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

Props

type
string
"button"
size
ButtonSize
config.default.size
"sm""2xs""xs""md""lg""xl"
target
"_blank" | "_parent" | "_self" | "_top" | (string & {})
to
string | RouteLocationAsRelativeGeneric | RouteLocationAsPathGeneric
activeClass
string
exactActiveClass
string
ariaCurrentValue
"page" | "step" | "location" | "date" | "time" | "true" | "false"
prefetchedClass
string
href
string | RouteLocationAsRelativeGeneric | RouteLocationAsPathGeneric
rel
any
ui
{ base?: string; font?: string; rounded?: string; truncate?: string; block?: string; inline?: string; size?: DeepPartial<{ '2xs': string; xs: string; sm: string; md: string; lg: string; xl: string; }, any>; ... 6 more ...; default?: DeepPartial<...>; } & { ...; } & { ...; }
{}
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
replace
boolean
noRel
boolean
prefetch
boolean
noPrefetch
boolean
external
boolean
truncate
boolean
false
block
boolean
false
square
boolean
false
loading
boolean
false
padded
boolean
true
trailing
boolean
false
leading
boolean
false
size
ButtonSize
null
"sm""2xs""xs""md""lg""xl"
ui
Partial<{ wrapper: { horizontal: string; vertical: string; }; rounded: string; shadow: string; orientation: { 'rounded-none': { horizontal: { start: string; end: string; }; vertical: { start: string; end: string; }; }; ... 7 more ...; 'rounded-full': { ...; }; }; }> & { ...; }
{}
orientation
"horizontal" | "vertical"
"horizontal"

Config

{
  base: 'focus:outline-none focus-visible:outline-0 disabled:cursor-not-allowed disabled:opacity-75 aria-disabled:cursor-not-allowed aria-disabled:opacity-75 flex-shrink-0',
  font: 'font-medium',
  rounded: 'rounded-md',
  truncate: 'text-left break-all line-clamp-1',
  block: 'w-full flex justify-center items-center',
  inline: 'inline-flex items-center',
  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 aria-disabled:bg-white dark:bg-gray-900 dark:hover:bg-gray-800/50 dark:disabled:bg-gray-900 dark:aria-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 aria-disabled:bg-gray-50 dark:bg-gray-800 dark:hover:bg-gray-700/50 dark:disabled:bg-gray-800 dark:aria-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 aria-disabled:bg-gray-900 dark:bg-white dark:hover:bg-gray-100 dark:disabled:bg-white dark:aria-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 aria-disabled:bg-{color}-500 dark:bg-{color}-400 dark:hover:bg-{color}-500 dark:disabled:bg-{color}-400 dark:aria-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 aria-disabled:bg-transparent dark:hover:bg-{color}-950 dark:disabled:bg-transparent dark:aria-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 aria-disabled:bg-{color}-50 dark:bg-{color}-950 dark:hover:bg-{color}-900 dark:disabled:bg-{color}-950 dark:aria-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 aria-disabled:bg-transparent dark:hover:bg-{color}-950 dark:disabled:bg-transparent dark:aria-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 aria-disabled:text-{color}-500 dark:text-{color}-400 dark:hover:text-{color}-500 dark:disabled:text-{color}-400 dark:aria-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',
    loading: 'animate-spin',
    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',
  orientation: {
    'rounded-none': {
      horizontal: {
        start: 'rounded-s-none',
        end: 'rounded-e-none',
      },
      vertical: {
        start: 'rounded-t-none',
        end: 'rounded-b-none',
      },
    },
    'rounded-sm': {
      horizontal: {
        start: 'rounded-s-sm',
        end: 'rounded-e-sm',
      },
      vertical: {
        start: 'rounded-t-sm',
        end: 'rounded-b-sm',
      },
    },
    rounded: {
      horizontal: {
        start: 'rounded-s',
        end: 'rounded-e',
      },
      vertical: {
        start: 'rounded-t',
        end: 'rounded-b',
      },
    },
    'rounded-md': {
      horizontal: {
        start: 'rounded-s-md',
        end: 'rounded-e-md',
      },
      vertical: {
        start: 'rounded-t-md',
        end: 'rounded-b-md',
      },
    },
    'rounded-lg': {
      horizontal: {
        start: 'rounded-s-lg',
        end: 'rounded-e-lg',
      },
      vertical: {
        start: 'rounded-t-lg',
        end: 'rounded-b-lg',
      },
    },
    'rounded-xl': {
      horizontal: {
        start: 'rounded-s-xl',
        end: 'rounded-e-xl',
      },
      vertical: {
        start: 'rounded-t-xl',
        end: 'rounded-b-xl',
      },
    },
    'rounded-2xl': {
      horizontal: {
        start: 'rounded-s-2xl',
        end: 'rounded-e-2xl',
      },
      vertical: {
        start: 'rounded-t-2xl',
        end: 'rounded-b-2xl',
      },
    },
    'rounded-3xl': {
      horizontal: {
        start: 'rounded-s-3xl',
        end: 'rounded-e-3xl',
      },
      vertical: {
        start: 'rounded-t-3xl',
        end: 'rounded-b-3xl',
      },
    },
    'rounded-full': {
      horizontal: {
        start: 'rounded-s-full',
        end: 'rounded-e-full',
      },
      vertical: {
        start: 'rounded-t-full',
        end: 'rounded-b-full',
      },
    },
  },
}

Breadcrumb

A list of links that indicate the current page's location within a navigational hierarchy.

Card

Display a card for content with a header, body and footer.