Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Actions

Button

An action button or styled link with editable variants, sizes, and a loading state.

Last changed in version 0.13.0: Add avatar groups and chips, expand the block gallery, and improve component colors, spacing, and motion.

Interactive showcase

Route link

Install

Run in your project
bunx --bun @getweini/cli@latest add button

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import Button from './components/ui/button/Button.vue'
</script>

<template>
  <Button variant="default">Save changes</Button>
  <Button variant="outline" size="sm">Cancel</Button>
</template>

Render a native button for actions or pass NuxtLink with as for navigation. asChild applies Button styling to one supplied child. Loading blocks repeat activation.

When to use it

Submit a form

Use type="submit" for the form’s primary action and show loading while the request is pending.

Secondary action

Use an outline or ghost button for an action that should not compete with the primary task.

Navigation action

Render an anchor through NuxtLink when a button-looking control changes pages.

More examples

Saving a form

The native submit type participates in form validation.

Saving a form
<script setup lang="ts">
import { ref } from 'vue'
import Button from './components/ui/button/Button.vue'

const saving = ref(false)
async function save() {
  saving.value = true
  try {
    await fetch('/api/profile', { method: 'POST' })
  } finally {
    saving.value = false
  }
}
</script>
<template>
  <form @submit.prevent="save">
    <Button type="submit" :loading="saving">Save profile</Button>
  </form>
</template>

Destructive action

Name the consequence in the button text.

Destructive action
<script setup lang="ts">
import Button from './components/ui/button/Button.vue'

function removeDraft() {
  /* Confirm or remove the draft here. */
}
</script>
<template>
  <Button variant="destructive" @click="removeDraft">Delete draft</Button>
</template>

NuxtLink owns the destination while Button supplies the Weini control treatment.

Nuxt route link
<script setup lang="ts">
import { NuxtLink } from '#components'
import Button from './components/ui/button/index.vue'
</script>
<template>
  <Button :as="NuxtLink" to="/guides/getting-started">Get started</Button>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Button

Complete API for Button
NameType or signatureDefaultWhat it does
asprop"button" | Component | "a" | undefined"button"Choose the HTML element or Vue component used for this control.
asChildpropboolean | undefinedNot setUse one child element as the control instead of adding another wrapper.
variantprop"default" | "destructive" | "secondary" | "outline" | "ghost" | undefined"default"Choose the visual treatment for this component.
sizeprop"sm" | "md" | "lg" | undefined"md"Choose the visual size. Medium is the usual default where available.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
loadingpropboolean | undefinedNot setShow that an action is in progress and prevent repeat activation.
typeprop"button" | "submit" | "reset" | undefined"button"Choose the native HTML control type or action behavior.
defaultslot() => unknownRequiredContent shown inside Button.
prefixslot(() => unknown) | undefinedOptionalContent shown before the main label or value.
suffixslot(() => unknown) | undefinedOptionalContent shown after the main label or value.
elementexposedHTMLElement | null—Reference to the underlying HTML element.
focusexposed() => void—Move keyboard focus to this control.
Public type definitions
Public types
// packages/frameworks/vue/components/button/types.ts
// ------- IMPORTS -------

export type { ButtonProps } from '@getweini/vue/types'


// packages/frameworks/vue/dist/types/index.d.ts
export type { ButtonOptions, ButtonProps } from './button';
export type ControlSize = 'sm' | 'md' | 'lg';
export interface SelectOption<T = unknown> {
    label: string;
    value: T;
    disabled?: boolean;
}
/** Application-owned copy. Bind translated strings reactively when the locale changes. */
export interface ListboxMessages {
    /** Popup name when no aria-label or aria-labelledby is supplied. */
    listboxLabel: string;
    empty: string;
    clearSelection: string;
}
export interface ListboxProps<T> {
    options: readonly SelectOption<T>[];
    messages: ListboxMessages;
    id?: string;
    disabled?: boolean;
    required?: boolean;
    invalid?: boolean;
    name?: string;
    form?: string;
    placeholder?: string;
    size?: ControlSize;
    clearable?: boolean;
    gap?: number;
    /** Supply stable equality for object values. Values must be unique. */
    by?: (a: T, b: T) => boolean;
    /** Required for meaningful form submission of object values. */
    serialize?: (value: T) => string;
}


// packages/frameworks/vue/dist/types/button.d.ts
import type { Component } from 'vue';
/** Options shared by button implementations across frameworks. */
export interface ButtonOptions<Variant extends string = string, Size extends string = string> {
    variant?: Variant;
    size?: Size;
    disabled?: boolean;
    loading?: boolean;
    type?: 'button' | 'submit' | 'reset';
}
/** Vue-specific target options extend the reusable button contract. */
export interface ButtonProps<Variant extends string = 'default' | 'secondary' | 'outline' | 'ghost' | 'destructive', Size extends string = 'sm' | 'md' | 'lg'> extends ButtonOptions<Variant, Size> {
    as?: 'button' | 'a' | Component;
    asChild?: boolean;
}

Implementation notes

  • The default type is button; set type="submit" or type="reset" explicitly when form behavior is intended.
  • Loading blocks another click and keeps the button’s accessible name and layout stable.
  • Pressing an enabled button gives a slight scale response; reduced-motion settings keep it still. The live example above uses the installed Button source.
  • Use as="a" with href or :as="NuxtLink" with to for navigation. Disabled and loading links do not navigate.

Accessibility and localization

  • Keep the default slot descriptive; supply an accessible name for an icon-only button.
  • Decorative icons in the prefix or suffix slot should use aria-hidden="true".

Source contract and editing guidance