# Button

Use Button for immediate actions such as submit, confirm, or a primary page action; use a link for navigation and Badge for passive status. It supports `solid`/`soft`/`outline`/`glass`, semantic `ActionColor` intent, `sm`/`md`/`lg`/`xl`/`2xl`, rounded/pill/FAB shapes, component-valued Lucide icons, disabled, and loading states. Soft uses a low-opacity palette fill and matching semantic text for secondary actions without an outline. Loading disables interaction and exposes `aria-busy`. Install with `npx balsa-ui@latest add button`. Dependencies: Vue, `@lucide/vue`, Icon, and the Balsa theme foundation. Canonical source: `src/components/ui/Button.vue`; interactive documentation: `/docs/components/button`; contract: `specs/components/button.json`.

Button inherits the nearest `data-theme` and accepts `theme?: ThemeInput` for a Modern Flat, Brutalism, or Glassmorphism override. In Brutalism, the default `rounded` shape resolves to `rounded-none`; use a consumer radius class when the context requires an override. `pill` and FAB follow the theme-owned pill radius, so they square off with everything else under a square shape recipe rather than staying round. In Glassmorphism, a solid primary Button keeps the active palette's exact primary state colors. Choose `glass` for a lower-emphasis translucent action with a restrained semantic rim and denser hover and active material states. Choose `outline` when the action needs a deliberately visible semantic boundary.

Use `shape="fab"` for an icon-only floating action. Its `sm`, `md`, `lg`, and `xl` presets follow the shared 32px, 36px, 40px, and 48px application scale; `2xl` is an intentional 72px display tier for a singular high-emphasis launcher. FABs are square and circular with no content padding and proportionally sized icons; provide `aria-label`, and position them in the consumer layout. With `:size="null"`, provide equal width and height classes alongside the FAB shape.

Use `prefixIcon` for a leading `IconComponent` and `suffixIcon` for a trailing one. Import individual symbols from `@lucide/vue`; the playground's generated source binds only the selected component.

Consumer classes are merged after Button defaults, so normal width, height, padding, typography, radius, and layout utilities can replace preset values. Use `:size="null"` when supplying a complete custom size; consumer `style` attributes are forwarded to the native button.

When the optional Analytics item is installed, `analytics-event="cta"` emits a named `cta` event in addition to the automatic `balsa_interaction`. Without Analytics the prop only publishes the inert provider-neutral `data-balsa-track` hook; Button never imports or initializes a vendor SDK.