🟢 Button

Basic

NButton - use to trigger an action or event, such as submitting a form, opening a dialog, canceling an action, or performing a delete operation.

You can use label prop or default slot to set the button text.

Variants

btn="{variant}" - change the variant of the button.

Variant	Description
`solid`	The default variant.
`outline`	The outline variant.
`ghost`	The ghost variant.
`link`	The link variant.
`soft`	The soft variant.
`text`	The text variant.
`~`	The unstyle or base variant

Color

btn="{variant}-{color}" - change the color of the button.

You can use any color provided by the Tailwind CSS color palette, the default is primary. You can also add your own colors to the palette through the Configuration section.

Dynamic colors:

Color with states:

Custom colors using utilities:

Static colors:

<template>
  <div class="flex flex-col gap-4">
    <span class="text-sm font-medium">Dynamic colors:</span>

    <div class="flex flex-col gap-4">
      <div class="flex flex-col gap-4 md:flex-row">
        <NButton
          label="solid-primary"
          btn="solid-primary"
        />
        <NButton
          label="outline-lime"
          btn="outline-lime"
        />
        <NButton
          label="link-yellow"
          btn="link-yellow"
        />
        <NButton
          label="soft-red"
          btn="soft-red"
        />
        <NButton
          label="ghost-orange"
          btn="ghost-orange"
        />
      </div>

      <NSeparator />

      <span class="text-sm font-medium">Color with states:</span>

      <div class="flex flex-col gap-4 md:flex-row">
        <NButton
          btn="solid-error hover:solid-success"
          label="hover me"
        />
        <NButton
          label="you can add transition too"
          class="transition delay-300 ease-in-out"
          btn="soft-error hover:soft-success"
        />
        <NButton
          btn="active:outline-fuchsia"
          label="click me"
        />
        <NButton
          label="click me"
          btn="outline-pink focus:outline-blue"
        />
      </div>

      <NSeparator />

      <span class="text-sm font-medium">Custom colors using utilities:</span>

      <div class="flex flex-col gap-2 md:flex-row">
        <NButton
          btn="~"
          class="from-primary to-$c-brand-next bg-gradient-to-r text-white hover:from-pink-500 hover:to-yellow-500"
          label="gradient color"
        />

        <NButton
          btn="~"
          class="from-primary-500 via-primary-600 to-primary-700 bg-gradient-to-r text-white shadow-lg shadow-primary-500/50 hover:bg-gradient-to-br dark:shadow-lg dark:shadow-primary-800/80 dark:focus:ring-primary-800"
          label="glowing effect"
        />
      </div>
    </div>

    <NSeparator />

    <span class="text-sm font-medium">Static colors:</span>

    <div class="flex flex-col gap-4">
      <div class="flex flex-col gap-2 md:flex-row">
        <NButton
          label="solid-gray"
          btn="solid-gray"
        />
        <NButton
          label="soft-gray"
          btn="soft-gray"
        />
        <NButton
          label="ghost-gray"
          btn="ghost-gray"
        />
        <NButton
          label="link-gray"
          btn="link-gray"
        />
      </div>

      <div class="flex flex-col gap-2 md:flex-row">
        <NButton
          label="solid-white"
          btn="solid-white"
        />
        <NButton
          label="ghost-white"
          btn="ghost-white"
        />
      </div>

      <div class="flex flex-col gap-2 md:flex-row">
        <NButton
          label="solid-black"
          btn="solid-black"
        />
        <NButton
          label="link-black"
          btn="link-black"
        />
      </div>

      <div class="flex flex-col gap-2 md:flex-row">
        <NButton
          label="text-black"
          btn="text-black"
        />
        <NButton
          label="text-gray"
          btn="text-gray"
        />
      </div>
    </div>
  </div>
</template>

Size

size="{size}" - change the size of the button.

🚀 You can freely adjust the size of the button using any size imaginable. No limits exist, and you can use breakpoints such as sm:sm, xs:lg to change size based on screen size or states such as hover:lg, focus:3xl to change size based on input state and more.

The padding and font-size of the button scale depends on the size. If you want to change the font-size and padding simultaneously, you can always customize it using utility classes.

Rounded

rounded="{size}" - change the border-radius of the button.

🚀 You can freely adjust the size of the rounded using any size imaginable. No limits exist, and you can use breakpoints such as sm:sm, xs:lg to change size based on screen size or states such as hover:lg, focus:3xl to change size based on input state and more.

You can use any size provided by the Tailwind CSS border-radius scale, the default is md. You can also add your own sizes to the scale through the Configuration section.

Square

square - to force width and height to have the same size, usefull for icon buttons.

🚀 You can freely adjust the square of the button using any size imaginable. No limits exist, and you can use breakpoints such as sm:sm, xs:lg to change size based on screen size or states such as hover:lg, focus:3xl to change size based on input state and more.

Props	Type	Default	Description
square	`string` `boolean`	`2.5em`	Set the button to have the same width and height. If you provide empty value or `true`, it will use the default value.

You can use any value provided by the Tailwind CSS. You can also add your own sizes to the scale through the Configuration section.

Icon

icon - change label text to icon.

leading="{icon}" - add a leading icon to the button.

trailing="{icon}" - add a trailing icon to the button.

By default we use heroicons and tabler for the icons, you can use any icon provided by Iconify through icones, refer to configuration for more information.

Icon buttons with and without square preset

Icon with states

Leading icon with label

Trailing icon with label

Link

to - add a link to the button.

Since we use NuxtLink for the link, you can use any NuxtLink props such as prefetch, target, activeClass, etc. Refer to NuxtLink for more information.

Previous page Next page Star us on GitHub Back to top

loading-placement - change the loading icon placement, default is leading. options are leading, trailing and label.

You can use loading with icon and label at the same time.

<script setup lang="ts">
const loading = ref(true)

function toggleLoading() {
  loading.value = !loading.value
}
</script>

<template>
  <div class="flex flex-col gap-4">
    <div>
      <NButton
        btn="solid-gray"
        :label="`Turn ${loading ? 'off' : 'on'} loading`"
        @click="toggleLoading"
      />
    </div>

    <NSeparator />

    <div class="flex flex-col gap-4 sm:flex-row">
      <NButton
        :loading="loading"
        :label="loading ? 'Leading...' : 'Leading'"
        @click="toggleLoading"
      />

      <NButton
        btn="soft-green"
        loading-placement="label"
        :loading="loading"
        :una="{
          btnLoadingIcon: 'i-tabler-loader-3',
        }"
        label="Label Loading"
        @click="toggleLoading"
      />

      <NButton
        btn="solid-black"
        loading-placement="trailing"
        :loading="loading"
        :una="{
          btnLoadingIcon: 'i-tabler-loader',
        }"
        :label="loading ? 'Trailing...' : 'Trailing'"
        @click="toggleLoading"
      />
    </div>

    <NSeparator />

    <div class="flex flex-col gap-4 sm:flex-row">
      <NButton
        btn="soft-yellow"
        :class="{ 'animate-pulse': loading }"
        :loading="loading"
        :label="loading ? 'Downloading...' : 'Download'"
        leading="i-heroicons-cloud-arrow-down-20-solid"
        @click="toggleLoading"
      />

      <NButton
        btn="link-orange"
        loading-placement="label"
        :loading="loading"
        :una="{
          btnLoadingIcon: 'i-heroicons-cloud-arrow-down-20-solid',
          btnLoading: 'animate-pulse',
        }"
        icon
        label="i-tabler-download"
        @click="toggleLoading"
      />

      <NButton
        btn="solid-white"
        loading-placement="label"
        :loading="loading"
        :una="{
          btnLoadingIcon: 'i-tabler-reload',
        }"
        label="Refresh"
        @click="toggleLoading"
      />
    </div>
  </div>
</template>

import type { HTMLAttributes } from 'vue'
import type { RouteLocationRaw } from 'vue-router'

interface BaseExtensionProps {
  square?: HTMLAttributes['class']
  rounded?: HTMLAttributes['class']
  class?: HTMLAttributes['class']
  breadcrumbActive?: string
  breadcrumbInactive?: string
  paginationSelected?: string
  paginationUnselected?: string
  dropdownMenu?: string
}

export interface NButtonProps extends BaseExtensionProps {
  /**
   * Change the button type.
   *
   * @default 'button'
   */
  type?: 'button' | 'submit' | 'reset'
  /**
   * Change the loading placement of the button.
   *
   * @default 'leading'
   */
  loadingPlacement?: 'leading' | 'trailing' | 'label'
  /**
   * Convert `label` prop to icon component.
   *
   * @default false
   * @example
   * icon
   * label="i-heroicons-information-circle"
   */
  icon?: boolean
  /**
   * Disable the button.
   *
   * @default false
   */
  disabled?: boolean
  /**
   * Swap the position of the leading and trailing icons.
   *
   * @default false
   */
  reverse?: boolean
  /**
   * Show loading state on button
   * @default false
   */
  loading?: boolean

  /**
   * Change the button tag to `NuxtLink` component,
   * This allows you to use `NuxtLink` available props.
   *
   * @see https://nuxt.com/docs/api/components/nuxt-link#props
   * @example
   * to="/"
   */
  to?: RouteLocationRaw
  /**
   * Add a label to the button.
   *
   * @example
   * label="Click me"
   */
  label?: string
  /**
   * Allows you to add `UnaUI` button preset properties,
   * Think of it as a shortcut for adding options or variants to the preset if available.
   *
   * @see https://github.com/una-ui/una-ui/blob/main/packages/preset/src/_shortcuts/button.ts
   * @example
   * btn="solid-green block square"
   */
  btn?: string
  /**
   * Add leading icon the button,
   * This also allows you to add utility classes to the icon.
   *
   * @example
   * leading="i-heroicons-information-circle text-green-500 dark:text-green-400 text-2xl"
   */
  leading?: string
  /**
   * Add trailing icon the button.
   * This also allows you to add utility classes to the icon.
   *
   * @example
   * trailing="i-heroicons-information-circle text-green-500 dark:text-green-400 text-2xl"
   */
  trailing?: string
  /**
   * Allows you to change the size of the input.
   *
   * @default sm
   *
   * @example
   * size="sm" | size="2cm" | size="2rem" | size="2px"
   */
  size?: string

  /**
   * `UnaUI` preset configuration
   *
   * @see https://github.com/una-ui/una-ui/blob/main/packages/preset/src/_shortcuts/button.ts
   */
  una?: {
    // base
    btnDefaultVariant?: string
    btn?: string
    btnLabel?: string
    btnIconLabel?: string
    btnLoading?: string

    // icons
    btnTrailing?: string
    btnLeading?: string
    btnLoadingIcon?: string
  }
}

Presets

type BtnPrefix = 'btn'

export const staticBtn: Record<`${BtnPrefix}-${string}` | BtnPrefix, string> = {
  // config
  'btn-default-variant': 'btn-solid',
  'btn-loading-icon': 'i-loading',
  'btn-default-radius': 'rounded-md',

  // base
  'btn': 'btn-rectangle px-0.7142857142857143em py-0.42857142857142855em bg-transparent transition-colors text-0.875em leading-5 gap-x-0.42857142857142855em rounded-md whitespace-nowrap inline-flex justify-center items-center btn-disabled font-medium cursor-pointer',
  'btn-disabled': 'disabled:n-disabled',
  'btn-label': '',
  'btn-icon-label': 'text-1.191em',
  'btn-leading': '-ml-0.14285714285714285em text-1.191em',
  'btn-trailing': '-mr-0.14285714285714285em text-1.191em',
  'btn-loading': 'animate-spin text-1.191em',
  'btn-rectangle': 'h-2.5em',
  'btn-square': 'w-2.5em h-2.5em',

  // options
  'btn-block': 'w-full',
  'btn-reverse': 'flex-row-reverse',

  // variants
  'btn-solid-white': 'bg-base text-base ring-1 ring-base ring-inset shadow-sm btn-focus hover:bg-muted',
  'btn-ghost-white': 'text-base btn-focus hover:bg-$c-gray-50',
  'btn-outline-white': 'text-base ring-1 ring-base ring-inset btn-focus',

  'btn-solid-gray': 'bg-$c-gray-50 text-$c-gray-800 ring-1 ring-base ring-inset shadow-sm btn-focus hover:bg-$c-gray-100',
  'btn-ghost-gray': 'text-$c-gray-600 btn-focus hover:bg-$c-gray-100',
  'btn-soft-gray': 'text-$c-gray-600 bg-$c-gray-50 btn-focus hover:bg-$c-gray-100',
  'btn-outline-gray': 'text-muted ring-1 ring-base ring-inset btn-focus',
  'btn-link-gray': 'text-muted btn-focus hover:text-base hover:underline underline-offset-4',
  'btn-text-gray': 'text-$c-gray-600 btn-focus hover:text-$c-gray-900',

  'btn-solid-black': 'bg-inverted text-inverted shadow-sm btn-focus',
  'btn-link-black': 'text-base btn-focus hover:underline underline-offset-4',
  'btn-text-black': 'text-base btn-focus',
  'btn-soft-black': 'text-base bg-base btn-focus shadow-sm',

  'btn-text-muted': 'text-muted btn-focus hover:text-accent',
}

export const dynamicBtn: [RegExp, (params: RegExpExecArray) => string][] = [
  // base
  [/^btn-focus(-(\S+))?$/, ([, , c = 'primary']) => `focus-visible:outline-${c}-600 dark:focus-visible:outline-${c}-500 focus-visible:outline-2 focus-visible:outline-offset-2`],

  // variants
  [/^btn-solid(-(\S+))?$/, ([, , c = 'primary']) => `btn-focus-${c} text-inverted shadow-sm bg-${c}-600 hover:bg-${c}-500 dark:bg-${c}-500 dark:hover:bg-${c}-400`],
  [/^btn-text(-(\S+))?$/, ([, , c = 'primary']) => `btn-focus-${c} text-${c}-600 dark:text-${c}-500 hover:text-${c}-500 dark:hover:text-${c}-400`],
  [/^btn-outline(-(\S+))?$/, ([, , c = 'primary']) => `btn-focus-${c} text-${c}-500 dark:text-${c}-400 ring-1 ring-inset ring-${c}-500 dark:ring-${c}-400 hover:bg-${c}-50 dark:hover:bg-${c}-950`],
  [/^btn-soft(-(\S+))?$/, ([, , c = 'primary']) => `btn-focus-${c} text-${c}-600 dark:text-${c}-400 bg-${c}-50 dark:bg-${c}-950 hover:bg-${c}-100 dark:hover:bg-${c}-900`],
  [/^btn-ghost(-(\S+))?$/, ([, , c = 'primary']) => `btn-focus-${c} text-${c}-600 dark:text-${c}-400 hover:bg-${c}-100 dark:hover:bg-${c}-900`],
  [/^btn-link(-(\S+))?$/, ([, , c = 'primary']) => `btn-focus-${c} text-${c}-500 dark:text-${c}-400 hover:underline underline-offset-4`],
]

export const btn = [
  ...dynamicBtn,
  staticBtn,
]

Component

<script setup lang="ts">
import type { NButtonProps } from '../../types'
import { createReusableTemplate } from '@vueuse/core'
import { computed } from 'vue'
import { cn } from '../../utils'
import NIcon from '../elements/Icon.vue'
import NLink from '../elements/Link.vue'

const props = withDefaults(defineProps<NButtonProps>(), {
  type: 'button',
  loadingPlacement: 'leading',
  square: false,
  una: () => ({
    btnDefaultVariant: 'btn-default-variant',
  }),
})

const mergeVariants = computed(() => {
  return {
    'btn': props.btn,
    'breadcrumb-active': props.breadcrumbActive,
    'breadcrumb-inactive': props.breadcrumbInactive,
    'pagination-selected': props.paginationSelected,
    'pagination-unselected': props.paginationUnselected,
    'dropdown-menu': props.dropdownMenu,
  }
})

const btnVariants = ['solid', 'outline', 'soft', 'ghost', 'link', 'text'] as const

const hasVariant = computed(() =>
  Object.values(mergeVariants.value).some(variantList =>
    btnVariants.some(variant => variantList?.includes(variant)),
  ),
)

const isBaseVariant = computed(() =>
  Object.values(mergeVariants.value).some(variantList =>
    variantList?.includes('~'),
  ),
)

const [DefineTemplate, ReuseTemplate] = createReusableTemplate()
</script>

<template>
  <Component
    :is="to ? NLink : 'button'"
    :to="to"
    :type="to ? null : type"
    :class="cn(
      (square === '' || square === true) && 'btn-square',
      !rounded && 'btn-default-radius',
      !hasVariant && !isBaseVariant ? una?.btnDefaultVariant : null,
      reverse && 'btn-reverse',
      'btn',
      una?.btn,
      props.class,
    )"
    :disabled="to ? null : disabled || loading"
    :aria-label="icon ? label : null"
    :rounded
    :size
    :square
    v-bind="mergeVariants"
  >
    <DefineTemplate v-if="loading">
      <slot name="loading">
        <NIcon
          :name="una?.btnLoadingIcon ?? 'btn-loading-icon'"
          :class="una?.btnLoading"
          btn="loading"
        />
      </slot>
    </DefineTemplate>

    <ReuseTemplate v-if="loading && loadingPlacement === 'leading'" />
    <slot
      v-else
      name="leading"
    >
      <NIcon
        v-if="leading"
        :name="leading"
        :class="una?.btnLeading"
        btn="leading"
      />
    </slot>

    <ReuseTemplate v-if="loading && loadingPlacement === 'label'" />

    <slot v-else>
      <NIcon
        v-if="label && icon"
        :name="label"
        btn="icon-label"
        :class="una?.btnIconLabel"
      />
      <span
        v-if="!icon"
        btn="label"
        :class="una?.btnLabel"
      >
        {{ label }}
      </span>
    </slot>

    <ReuseTemplate v-if="loading && loadingPlacement === 'trailing'" />
    <slot
      v-else
      name="trailing"
    >
      <NIcon
        v-if="trailing"
        :name="trailing"
        btn="trailing"
        :class="una?.btnTrailing"
      />
    </slot>
  </Component>
</template>

Edit this page on GitHub

Components🟢 Breadcrumb

Components🟢 Card

🟢 Button

Basic

Variants

Color

Size

Rounded

Square

Icon

Link

Block

Disabled

Loading

Slots

Default

Leading

Trailing

Loading

Props

Presets

Component