Vinicunca

Button

GitHub
A button element that can act as a link or trigger an action.

Usage

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

<template>
  <PButton>Button</PButton>
</template>

Label

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

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

Color

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

<template>
  <PButton color="neutral">Button</PButton>
</template>

Variant

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

<template>
  <PButton color="neutral" variant="outline">Button</PButton>
</template>

Size

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

<template>
  <PButton size="xl">Button</PButton>
</template>

Icon

Use the icon prop to show an Icon inside the Button.

<template>
  <PButton icon="i-lucide-rocket" size="md" color="primary" variant="solid">Button</PButton>
</template>

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>
  <PButton trailing-icon="i-lucide-arrow-right" size="md">Button</PButton>
</template>

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

<template>
  <PButton icon="i-lucide-search" size="md" color="primary" variant="solid" />
</template>

Avatar

Use the avatar prop to show an Avatar inside the Button.

<template>
  <PButton
    :avatar="{
      src: 'https://github.com/nuxt.png',
      loading: 'lazy'
    }"
    size="md"
    color="neutral"
    variant="outline"
  >
    Button
  </PButton>
</template>

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

<template>
  <PButton
    :avatar="{
      src: 'https://github.com/nuxt.png',
      loading: 'lazy'
    }"
    size="md"
    color="neutral"
    variant="outline"
  />
</template>

Link

You can pass any property from the Link component such as to, target, etc.

Button
<template>
  <PButton to="https://github.com/vinicunca/pohon" target="_blank">Button</PButton>
</template>

When the Button is a link or when using the active prop, you can use the active-color and active-variant props to customize the active state.

<template>
  <PButton active color="neutral" variant="outline" active-color="primary" active-variant="solid">
    Button
  </PButton>
</template>

You can also use the active-class and inactive-class props to customize the active state.

<template>
  <PButton active active-class="font-bold" inactive-class="font-light">Button</PButton>
</template>
You can configure these styles globally in your app.config.ts file under the ui.button.variants.active key.
export default defineAppConfig({
  ui: {
    button: {
      variants: {
        active: {
          true: {
            base: 'font-bold'
          }
        }
      }
    }
  }
});

Loading

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

<template>
  <PButton loading>Button</PButton>
</template>

Use the loading-auto prop to show the loading icon automatically while the @click promise is pending.

<script setup lang="ts">
async function onClick() {
  return new Promise<void>((res) => setTimeout(res, 1000));
}
</script>

<template>
  <PButton
    loading-auto
    @click="onClick"
  >
    Button
  </PButton>
</template>

This also works with the Form component.

<script setup lang="ts">
const state = reactive({ fullName: '' });

async function onSubmit() {
  return new Promise<void>((res) => setTimeout(res, 1000));
}

async function validate(data: Partial<typeof state>) {
  if (!data.fullName?.length) {
    return [{ name: 'fullName', message: 'Required' }];
  }
  return [];
}
</script>

<template>
  <PForm
    :state="state"
    :validate="validate"
    @submit="onSubmit"
  >
    <PFormField
      name="fullName"
      label="Full name"
    >
      <PInput v-model="state.fullName" />
    </PFormField>
    <PButton
      type="submit"
      class="mt-2"
      loading-auto
    >
      Submit
    </PButton>
  </PForm>
</template>

<script setup lang="ts">
import { reactive } from 'vue'

const state = reactive({ fullName: '' });

async function onSubmit() {
  return new Promise<void>((res) => setTimeout(res, 1000));
}

async function validate(data: Partial<typeof state>) {
  if (!data.fullName?.length) {
    return [{ name: 'fullName', message: 'Required' }];
  }
  return [];
}
</script>

<template>
  <PForm
    :state="state"
    :validate="validate"
    @submit="onSubmit"
  >
    <PFormField
      name="fullName"
      label="Full name"
    >
      <PInput v-model="state.fullName" />
    </PFormField>
    <PButton
      type="submit"
      class="mt-2"
      loading-auto
    >
      Submit
    </PButton>
  </PForm>
</template>

Loading Icon

Use the loading-icon prop to customize the loading icon. Defaults to i-lucide-loader-circle.

<template>
  <PButton loading loading-icon="i-lucide-loader">Button</PButton>
</template>
You can customize this icon globally in your app.config.ts under ui.icons.loading key.
You can customize this icon globally in your vite.config.ts under ui.icons.loading key.

Disabled

Use the disabled prop to disable the Button.

<template>
  <PButton disabled>Button</PButton>
</template>

Examples

class prop

Use the class prop to override the base styles of the Button.

<template>
  <PButton class="font-bold rounded-full">Button</PButton>
</template>

ui prop

Use the ui prop to override the slots styles of the Button.

<template>
  <PButton
    icon="i-lucide-rocket"
    color="neutral"
    variant="outline"
    :ui="{
      leadingIcon: 'color-primary'
    }"
  >
    Button
  </PButton>
</template>

API

Props

Prop Default Type
as
'button'
any

The element or component this component should render as when not a link.

label
string
color
'primary'
"primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral"
activeColor
"primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral"
variant
'solid'
"solid" | "outline" | "soft" | "subtle" | "ghost" | "link"
activeVariant
"solid" | "outline" | "soft" | "subtle" | "ghost" | "link"
size
'md'
"xs" | "sm" | "md" | "lg" | "xl"
square
boolean

Render the button with equal padding on all sides.

block
boolean

Render the button full width.

loadingAuto
boolean

Set loading state automatically based on the @click promise state

icon
any

Display an icon based on the leading and trailing props.

avatar
AvatarProps

Display an avatar on the left side.

leading
boolean

When true, the icon will be displayed on the left side.

leadingIcon
any

Display an icon on the left side.

trailing
boolean

When true, the icon will be displayed on the right side.

trailingIcon
any

Display an icon on the right side.

loading
boolean

When true, the loading icon will be displayed.

loadingIcon
appConfig.ui.icons.loading
any

The icon when the loading prop is true.

to
string | et | X

Route Location the link should navigate to when clicked on.

autofocus
false | true | "true" | "false"
disabled
boolean
name
string
type
'button'
"button" | "submit" | "reset"

The type of the button when not a link.

download
any
hreflang
string
media
string
ping
string
target
null | string | "_blank" | "_parent" | "_self" | "_top"

Where to display the linked URL, as the name for a browsing context.

referrerpolicy
"" | "no-referrer" | "no-referrer-when-downgrade" | "origin" | "origin-when-cross-origin" | "same-origin" | "strict-origin" | "strict-origin-when-cross-origin" | "unsafe-url"
active
boolean

Force the link to be active independent of the current route.

locale
string | false | true

Control i18n auto-localization when @nuxtjs/i18n is installed.

  • undefined / true (default): auto-localizes to the current locale using $localePath. Paths already carrying a locale prefix (from e.g. switchLocalePath()) are detected and left untouched to prevent double-prefixing.
  • false: explicitly disables auto-localization.
  • string: localizes to a specific locale (e.g. 'fr').
trailingSlash
"append" | "remove"

An option to either add or remove trailing slashes in the href for this specific link. Overrides the global trailingSlash option if provided.

ui
{ base?: SlotClass; label?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailingIcon?: SlotClass; }
This component also supports all native <button> HTML attributes.
The Button component extends the Link component. Check out the source code on GitHub.

Slots

Slot Type
leading
{ ui: object; }
default
{ ui: object; }
trailing
{ ui: object; }

Theme

app.config.ts
export default defineAppConfig({
  ui: {
    button: {
      slots: {
        base: [
          'font-500 rounded-md inline-flex items-center aria-disabled:opacity-75 aria-disabled:cursor-not-allowed disabled:opacity-75 disabled:cursor-not-allowed',
          'transition-colors'
        ],
        label: 'truncate',
        leadingIcon: 'shrink-0',
        leadingAvatar: 'shrink-0',
        leadingAvatarSize: '',
        trailingIcon: 'shrink-0'
      },
      variants: {
        fieldGroup: {
          horizontal: 'first:not-[*:only-child]:rounded-e-none last:not-[*:only-child]:rounded-s-none not-last:not-first:rounded-none focus-visible:z-1',
          vertical: 'first:not-[*:only-child]:rounded-b-none last:not-[*:only-child]:rounded-t-none not-last:not-first:rounded-none focus-visible:z-1'
        },
        color: {
          primary: '',
          secondary: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        variant: {
          solid: '',
          outline: '',
          soft: '',
          subtle: '',
          ghost: '',
          link: ''
        },
        size: {
          xs: {
            base: 'text-xs gap-1',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4'
          },
          sm: {
            base: 'text-xs gap-1.5',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4'
          },
          md: {
            base: 'text-sm gap-1.5',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5'
          },
          lg: {
            base: 'text-sm gap-2',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5'
          },
          xl: {
            base: 'text-base gap-2',
            leadingIcon: 'size-6',
            leadingAvatarSize: 'xs',
            trailingIcon: 'size-6'
          }
        },
        block: {
          true: {
            base: 'w-full justify-center',
            trailingIcon: 'ms-auto'
          }
        },
        square: {
          true: ''
        },
        leading: {
          true: ''
        },
        trailing: {
          true: ''
        },
        loading: {
          true: ''
        },
        active: {
          true: {
            base: ''
          },
          false: {
            base: ''
          }
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          variant: 'solid',
          class: 'color-primary-foreground bg-primary hover:bg-primary/75 active:bg-primary/75 disabled:bg-primary aria-disabled:bg-primary outline-primary/25 focus-visible:outline-3'
        },
        {
          color: 'primary',
          variant: 'outline',
          class: 'ring ring-inset ring-primary/50 color-primary hover:bg-primary/10 active:bg-primary/10 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent outline-primary/25 focus-visible:outline-3 focus-visible:ring-primary'
        },
        {
          color: 'primary',
          variant: 'soft',
          class: 'color-primary bg-primary/10 hover:bg-primary/15 active:bg-primary/15 outline-primary/25 focus-visible:outline-3 disabled:bg-primary/10 aria-disabled:bg-primary/10'
        },
        {
          color: 'primary',
          variant: 'subtle',
          class: 'color-primary ring ring-inset ring-primary/25 bg-primary/10 hover:bg-primary/15 active:bg-primary/15 disabled:bg-primary/10 aria-disabled:bg-primary/10 outline-primary/25 focus-visible:outline-3 focus-visible:ring-primary'
        },
        {
          color: 'primary',
          variant: 'ghost',
          class: 'color-primary hover:bg-primary/10 active:bg-primary/10 outline-primary/25 focus-visible:outline-3 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent'
        },
        {
          color: 'primary',
          variant: 'link',
          class: 'color-primary hover:color-primary/75 active:color-primary/75 disabled:color-primary aria-disabled:color-primary outline-primary/25 focus-visible:outline-3'
        },
        {
          color: 'neutral',
          variant: 'solid',
          class: 'color-text-inverted bg-background-inverted hover:bg-background-inverted/90 active:bg-background-inverted/90 disabled:bg-background-inverted aria-disabled:bg-background-inverted outline-border-inverted/25 focus-visible:outline-3'
        },
        {
          color: 'neutral',
          variant: 'outline',
          class: 'ring ring-inset ring-border-accented color-text bg-background hover:bg-background-elevated active:bg-background-elevated disabled:bg-background aria-disabled:bg-background outline-border-inverted/25 focus-visible:outline-3 focus-visible:ring-border-inverted'
        },
        {
          color: 'neutral',
          variant: 'soft',
          class: 'color-text bg-background-elevated hover:bg-background-accented/75 active:bg-background-accented/75 outline-border-inverted/25 focus-visible:outline-3 disabled:bg-background-elevated aria-disabled:bg-background-elevated'
        },
        {
          color: 'neutral',
          variant: 'subtle',
          class: 'ring ring-inset ring-border-accented color-text bg-background-elevated hover:bg-background-accented/75 active:bg-background-accented/75 disabled:bg-background-elevated aria-disabled:bg-background-elevated outline-border-inverted/25 focus-visible:outline-3 focus-visible:ring-border-inverted'
        },
        {
          color: 'neutral',
          variant: 'ghost',
          class: 'color-text hover:bg-background-elevated active:bg-background-elevated outline-border-inverted/25 focus-visible:outline-3 hover:disabled:bg-transparent dark:hover:disabled:bg-transparent hover:aria-disabled:bg-transparent dark:hover:aria-disabled:bg-transparent'
        },
        {
          color: 'neutral',
          variant: 'link',
          class: 'color-text-muted hover:color-text active:color-text disabled:color-text-muted aria-disabled:color-text-muted outline-border-inverted/25 focus-visible:outline-3'
        },
        {
          size: 'xs',
          square: false,
          class: 'px-2 py-1'
        },
        {
          size: 'xs',
          square: true,
          class: 'p-1'
        },
        {
          size: 'sm',
          square: false,
          class: 'px-2.5 py-1.5'
        },
        {
          size: 'sm',
          square: true,
          class: 'p-1.5'
        },
        {
          size: 'md',
          square: false,
          class: 'px-2.5 py-1.5'
        },
        {
          size: 'md',
          square: true,
          class: 'p-1.5'
        },
        {
          size: 'lg',
          square: false,
          class: 'px-3 py-2'
        },
        {
          size: 'lg',
          square: true,
          class: 'p-2'
        },
        {
          size: 'xl',
          square: false,
          class: 'px-3 py-2'
        },
        {
          size: 'xl',
          square: true,
          class: 'p-2'
        },
        {
          loading: true,
          leading: true,
          class: {
            leadingIcon: 'animate-spin'
          }
        },
        {
          loading: true,
          leading: false,
          trailing: true,
          class: {
            trailingIcon: 'animate-spin'
          }
        }
      ],
      defaultVariants: {
        color: 'primary',
        variant: 'solid',
        size: 'md'
      }
    }
  }
})
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from 'pohon-ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        button: {
          slots: {
            base: [
              'font-500 rounded-md inline-flex items-center aria-disabled:opacity-75 aria-disabled:cursor-not-allowed disabled:opacity-75 disabled:cursor-not-allowed',
              'transition-colors'
            ],
            label: 'truncate',
            leadingIcon: 'shrink-0',
            leadingAvatar: 'shrink-0',
            leadingAvatarSize: '',
            trailingIcon: 'shrink-0'
          },
          variants: {
            fieldGroup: {
              horizontal: 'first:not-[*:only-child]:rounded-e-none last:not-[*:only-child]:rounded-s-none not-last:not-first:rounded-none focus-visible:z-1',
              vertical: 'first:not-[*:only-child]:rounded-b-none last:not-[*:only-child]:rounded-t-none not-last:not-first:rounded-none focus-visible:z-1'
            },
            color: {
              primary: '',
              secondary: '',
              success: '',
              info: '',
              warning: '',
              error: '',
              neutral: ''
            },
            variant: {
              solid: '',
              outline: '',
              soft: '',
              subtle: '',
              ghost: '',
              link: ''
            },
            size: {
              xs: {
                base: 'text-xs gap-1',
                leadingIcon: 'size-4',
                leadingAvatarSize: '3xs',
                trailingIcon: 'size-4'
              },
              sm: {
                base: 'text-xs gap-1.5',
                leadingIcon: 'size-4',
                leadingAvatarSize: '3xs',
                trailingIcon: 'size-4'
              },
              md: {
                base: 'text-sm gap-1.5',
                leadingIcon: 'size-5',
                leadingAvatarSize: '2xs',
                trailingIcon: 'size-5'
              },
              lg: {
                base: 'text-sm gap-2',
                leadingIcon: 'size-5',
                leadingAvatarSize: '2xs',
                trailingIcon: 'size-5'
              },
              xl: {
                base: 'text-base gap-2',
                leadingIcon: 'size-6',
                leadingAvatarSize: 'xs',
                trailingIcon: 'size-6'
              }
            },
            block: {
              true: {
                base: 'w-full justify-center',
                trailingIcon: 'ms-auto'
              }
            },
            square: {
              true: ''
            },
            leading: {
              true: ''
            },
            trailing: {
              true: ''
            },
            loading: {
              true: ''
            },
            active: {
              true: {
                base: ''
              },
              false: {
                base: ''
              }
            }
          },
          compoundVariants: [
            {
              color: 'primary',
              variant: 'solid',
              class: 'color-primary-foreground bg-primary hover:bg-primary/75 active:bg-primary/75 disabled:bg-primary aria-disabled:bg-primary outline-primary/25 focus-visible:outline-3'
            },
            {
              color: 'primary',
              variant: 'outline',
              class: 'ring ring-inset ring-primary/50 color-primary hover:bg-primary/10 active:bg-primary/10 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent outline-primary/25 focus-visible:outline-3 focus-visible:ring-primary'
            },
            {
              color: 'primary',
              variant: 'soft',
              class: 'color-primary bg-primary/10 hover:bg-primary/15 active:bg-primary/15 outline-primary/25 focus-visible:outline-3 disabled:bg-primary/10 aria-disabled:bg-primary/10'
            },
            {
              color: 'primary',
              variant: 'subtle',
              class: 'color-primary ring ring-inset ring-primary/25 bg-primary/10 hover:bg-primary/15 active:bg-primary/15 disabled:bg-primary/10 aria-disabled:bg-primary/10 outline-primary/25 focus-visible:outline-3 focus-visible:ring-primary'
            },
            {
              color: 'primary',
              variant: 'ghost',
              class: 'color-primary hover:bg-primary/10 active:bg-primary/10 outline-primary/25 focus-visible:outline-3 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent'
            },
            {
              color: 'primary',
              variant: 'link',
              class: 'color-primary hover:color-primary/75 active:color-primary/75 disabled:color-primary aria-disabled:color-primary outline-primary/25 focus-visible:outline-3'
            },
            {
              color: 'neutral',
              variant: 'solid',
              class: 'color-text-inverted bg-background-inverted hover:bg-background-inverted/90 active:bg-background-inverted/90 disabled:bg-background-inverted aria-disabled:bg-background-inverted outline-border-inverted/25 focus-visible:outline-3'
            },
            {
              color: 'neutral',
              variant: 'outline',
              class: 'ring ring-inset ring-border-accented color-text bg-background hover:bg-background-elevated active:bg-background-elevated disabled:bg-background aria-disabled:bg-background outline-border-inverted/25 focus-visible:outline-3 focus-visible:ring-border-inverted'
            },
            {
              color: 'neutral',
              variant: 'soft',
              class: 'color-text bg-background-elevated hover:bg-background-accented/75 active:bg-background-accented/75 outline-border-inverted/25 focus-visible:outline-3 disabled:bg-background-elevated aria-disabled:bg-background-elevated'
            },
            {
              color: 'neutral',
              variant: 'subtle',
              class: 'ring ring-inset ring-border-accented color-text bg-background-elevated hover:bg-background-accented/75 active:bg-background-accented/75 disabled:bg-background-elevated aria-disabled:bg-background-elevated outline-border-inverted/25 focus-visible:outline-3 focus-visible:ring-border-inverted'
            },
            {
              color: 'neutral',
              variant: 'ghost',
              class: 'color-text hover:bg-background-elevated active:bg-background-elevated outline-border-inverted/25 focus-visible:outline-3 hover:disabled:bg-transparent dark:hover:disabled:bg-transparent hover:aria-disabled:bg-transparent dark:hover:aria-disabled:bg-transparent'
            },
            {
              color: 'neutral',
              variant: 'link',
              class: 'color-text-muted hover:color-text active:color-text disabled:color-text-muted aria-disabled:color-text-muted outline-border-inverted/25 focus-visible:outline-3'
            },
            {
              size: 'xs',
              square: false,
              class: 'px-2 py-1'
            },
            {
              size: 'xs',
              square: true,
              class: 'p-1'
            },
            {
              size: 'sm',
              square: false,
              class: 'px-2.5 py-1.5'
            },
            {
              size: 'sm',
              square: true,
              class: 'p-1.5'
            },
            {
              size: 'md',
              square: false,
              class: 'px-2.5 py-1.5'
            },
            {
              size: 'md',
              square: true,
              class: 'p-1.5'
            },
            {
              size: 'lg',
              square: false,
              class: 'px-3 py-2'
            },
            {
              size: 'lg',
              square: true,
              class: 'p-2'
            },
            {
              size: 'xl',
              square: false,
              class: 'px-3 py-2'
            },
            {
              size: 'xl',
              square: true,
              class: 'p-2'
            },
            {
              loading: true,
              leading: true,
              class: {
                leadingIcon: 'animate-spin'
              }
            },
            {
              loading: true,
              leading: false,
              trailing: true,
              class: {
                trailingIcon: 'animate-spin'
              }
            }
          ],
          defaultVariants: {
            color: 'primary',
            variant: 'solid',
            size: 'md'
          }
        }
      }
    })
  ]
})
Some colors in compoundVariants are omitted for readability. Check out the source code on GitHub.

Changelog

No recent changes

Banner

Display a banner at the top of your website to inform users about important information.

Calendar

A calendar component for selecting single dates, multiple dates or date ranges.