Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Actions

IconButton

An icon-only button with an accessible label, loading state, and three sizes.

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

Install

Run in your project
bunx --bun @getweini/cli@latest add icon-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 IconButton from './components/ui/icon-button/IconButton.vue'
</script>

<template>
  <IconButton aria-label="Add item" variant="outline">
    <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
      <path d="M12 5v14M5 12h14" />
    </svg>
  </IconButton>
</template>

Name the button with aria-label, aria-labelledby, or the label prop. Put a decorative SVG in the default or #icon slot. Native attributes and click events pass through; loading prevents repeat clicks.

When to use it

Compact row action

Place a named icon action at the end of a list row or toolbar.

Asynchronous action

Use loading while an icon action is in progress to prevent repeated activation.

More examples

Close a panel

The label names the action independently of its glyph.

Close a panel
<script setup lang="ts">
import IconButton from './components/ui/icon-button/IconButton.vue'

const emit = defineEmits<{ close: [] }>()
</script>
<template>
  <IconButton label="Close panel" variant="ghost" @click="emit('close')">
    <template #icon>
      <svg aria-hidden="true" viewBox="0 0 24 24">
        <path d="M5 5l14 14M19 5L5 19" stroke="currentColor" fill="none" />
      </svg>
    </template>
  </IconButton>
</template>

Busy refresh control

The visual icon gives way to a spinner while refreshing.

Busy refresh control
<script setup lang="ts">
import { ref } from 'vue'
import IconButton from './components/ui/icon-button/IconButton.vue'

const refreshing = ref(false)
async function refresh() {
  refreshing.value = true
  try {
    await fetch('/api/items')
  } finally {
    refreshing.value = false
  }
}
</script>
<template>
  <IconButton label="Refresh items" :loading="refreshing" @click="refresh">
    <template #icon>
      <svg aria-hidden="true" viewBox="0 0 24 24">
        <path d="M20 12a8 8 0 1 1-2-5" stroke="currentColor" fill="none" />
      </svg>
    </template>
  </IconButton>
</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.

IconButton

Complete API for IconButton
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.
labelpropstring | undefinedNot setCompatibility shorthand for aria-label.
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(() => unknown) | undefinedOptionalContent shown inside IconButton.
iconslot(() => unknown) | undefinedOptionalContent for the icon area of IconButton.
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/icon-button/types.ts
// ------- IMPORTS -------

import type { Component } from 'vue'
import type { iconButtonSizes, iconButtonVariants } from './styles'

// ------- TYPES -------

export interface IconButtonProps {
  as?: 'button' | 'a' | Component
  asChild?: boolean
  /** Compatibility shorthand for aria-label. */
  label?: string
  variant?: keyof typeof iconButtonVariants
  size?: keyof typeof iconButtonSizes
  disabled?: boolean
  loading?: boolean
  type?: 'button' | 'submit' | 'reset'
}


// packages/frameworks/vue/components/icon-button/styles.ts
// Edit visual variants and sizes here; the public visual prop types follow these keys.
export const iconButtonVariants = {
  default: 'bg-primary text-primary-foreground hover:bg-primary-hover',
  secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary-hover',
  outline:
    'border border-control-border bg-clip-padding bg-control text-foreground hover:bg-secondary',
  ghost: 'text-foreground hover:bg-secondary',
  destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive-hover',
} as const

export const iconButtonSizes = { sm: 'size-8', md: 'size-10', lg: 'size-12' } as const
export const iconSizes: Record<keyof typeof iconButtonSizes, string> = {
  sm: 'size-4',
  md: 'size-5',
  lg: 'size-6',
}

Implementation notes

  • The icon slot is visual decoration; aria-label, aria-labelledby or the label prop supplies the accessible name.
  • Sizes sm, md, and lg have square 32, 40, and 48 pixel targets.
  • Enabled icon actions scale slightly while pressed; reduced-motion settings keep them still.

Accessibility and localization

  • Translate the label prop with the surrounding interface.
  • Keep the slotted SVG aria-hidden and avoid interactive content inside the button.

Source contract and editing guidance