# Balsa UI

> Agent-native, open-code Vue 3 components with independent palettes, design themes, and gradient backgrounds.

Use Balsa when building Vue 3 + TypeScript + Tailwind CSS 4 interfaces.

## Required agent workflow

In an existing Vue project, run these commands before writing common controls or surfaces:

```sh
npx balsa-ui@latest init
npx balsa-ui@latest search "settings form"
npx balsa-ui@latest info input --markdown
npx balsa-ui@latest add input button modal
```

Do not rebuild a matching Balsa component with raw HTML and CSS. The selected specification is sufficient for normal composition; inspect installed source only when changing component behavior.

## Focused references

- [Agent quick start](https://balsa-ui.com/agent/quick-start.md)
- [Compact catalog](https://balsa-ui.com/catalog-index.json)
- [Optional complete component listing](https://balsa-ui.com/llms-full.txt)
- [Installation](https://balsa-ui.com/docs/installation)
- [CLI](https://balsa-ui.com/docs/cli)
- [Template design skill](https://balsa-ui.com/agent/skills/balsa-template-design/SKILL.md)

## Components

- [Icon](https://balsa-ui.com/docs/components/icon.md): Tree-shaken Lucide icon primitive with finite sizing and stroke weight plus decorative or labelled accessibility semantics.
- [Analytics](https://balsa-ui.com/docs/components/analytics.md): Provider-neutral interaction tracking for every data-balsa component, with consent gating, typed custom events, and adapters for GA4, Meta Pixel, LinkedIn Insight Tag, or application-owned destinations.
- [Button](https://balsa-ui.com/docs/components/button.md): Typed action control with solid, soft, outline, and glass styles, rounded, pill, and FAB shapes, loading state, sizes, and Lucide icons.
- [ButtonGroup](https://balsa-ui.com/docs/components/button-group.md): Connected mutually exclusive actions with semantic color, a Glassmorphism-aware surface-to-glass default, explicit surface, solid, outline, glass, and compact code treatments; rounded or pill outer shapes; four shared sizes; responsive labels; and accessible pressed state.
- [Input](https://balsa-ui.com/docs/components/input.md): Accessible labeled native and masked input with outline, surface, soft, and glass materials; compact and default sizes; configurable geometry; password, phone, monetary, and percentage modes; validation feedback; and loading states.
- [Input Group](https://balsa-ui.com/docs/components/input-group.md): One labelled native text input with typed start/end text or Lucide addons, action slots, inline or stacked layout, shared form sizing and geometry, and complete required, disabled, loading, validated, and unvalidated behavior.
- [Input OTP](https://balsa-ui.com/docs/components/input-otp.md): One accessible fixed-length native verification-code input with semantic-colored visual cells, numeric or alphanumeric filtering, paste and caret editing, optional masking and grouping, surface/outline/soft/solid/glass materials, completion events, and shared form states.
- [Radio Group](https://balsa-ui.com/docs/components/radio-group.md): Accessible native mutually exclusive choices with typed options, a default column layout, semantic selected colors, row and selected-card layouts, shared form validation, sizing, geometry, and loading behavior.
- [Slider](https://balsa-ui.com/docs/components/slider.md): Single-value and independently draggable bounded-range native sliders with horizontal and vertical orientation, formatted output, three sizes, minimum thumb gaps, keyboard, pointer, touch, and form behavior.
- [Popup](https://balsa-ui.com/docs/components/popup.md): Collision-aware interactive rich content anchored to a native button with portal or contained rendering, focus entry/restoration, dismissal, typed materials, sizing, and geometry.
- [Hover Card](https://balsa-ui.com/docs/components/hover-card.md): Delayed pointer-hover and keyboard-focus previews that preserve focus, bridge pointer movement, collision-flip, escape clipping, and inherit Balsa materials and geometry.
- [Tooltip](https://balsa-ui.com/docs/components/tooltip.md): Collision-aware non-interactive supplementary descriptions for pointer hover and keyboard focus, with typed timing, materials, geometry, portal or contained rendering, and theme inheritance.
- [Dropdown Menu](https://balsa-ui.com/docs/components/dropdown-menu.md): Button-triggered typed action menus with labels, separators, checkbox/radio state, destructive items, shortcuts, submenus, semantic color, configurable geometry, roving focus, typeahead, and collision-safe portals. Ships PropertySelect, the full-width caption-over-value property row built on the same trigger.
- [Context Menu](https://balsa-ui.com/docs/components/context-menu.md): Pointer- and keyboard-positioned typed context actions with viewport collision handling and the complete shared Balsa menu semantics.
- [Menubar](https://balsa-ui.com/docs/components/menubar.md): Persistent application menus with horizontal roving focus, open-menu transfer, typed shared menu content, portals, and complete keyboard behavior.
- [Command Menu](https://balsa-ui.com/docs/components/command-menu.md): Inline dropdown or on-demand dialog grouped command filtering with combobox/listbox semantics, active-descendant navigation, hotkey opening, loading, empty states, and typed sizing.
- [Drawer](https://balsa-ui.com/docs/components/drawer.md): Native modal edge panel with four sides, three extents, scrollable slots, focus/scroll management, dismissal policy, handle drag, and contained previews.
- [ColorPicker](https://balsa-ui.com/docs/components/color-picker.md): Accessible contrast-safe outline, surface, soft, or glass color field or grouped palette trigger with a custom saturation, hue, and editable HEX, RGB, or HSL color-code popover.
- [Modal](https://balsa-ui.com/docs/components/modal.md): Typed semantic-color surface, solid, outline, soft, or glass focused dialog or bottom sheet with accessible naming, focus containment and return, Escape handling, backdrop dismissal, and background scroll locking that preserves scrolling inside the dialog.
- [Textarea](https://balsa-ui.com/docs/components/textarea.md): Accessible multi-line input with outline, surface, soft, and glass materials; typed size and radius; rows; auto expansion; capped height; resize behavior; and validation feedback.
- [Breadcrumb](https://balsa-ui.com/docs/components/breadcrumb.md): Typed compact hierarchy navigation with linked ancestors, a current-page state, selectable separators, and accessible ordered-list semantics.
- [Link](https://balsa-ui.com/docs/components/link.md): Typed sized navigation link with text, solid, and outline presentations, optional square geometry, and safe external-link behavior.
- [Badge](https://balsa-ui.com/docs/components/badge.md): Compact status, category, and metadata label with solid, soft, outline, and low-rim translucent glass styles, three sizes, and optional square geometry.
- [Card](https://balsa-ui.com/docs/components/card.md): Consistent semantic surface with six variants, typed action-intent color, configurable corners, size or padding, and shadow for grouping related content and actions.
- [ApplicationCard](https://balsa-ui.com/docs/components/application-card.md): Structured application surface with a repeatable header, action, body, and footer rhythm that inherits Card material, geometry, borders, density, and elevation.
- [Select](https://balsa-ui.com/docs/components/select.md): Keyboard-accessible outline, surface, soft, or glass single or multiple selection with compact sizing, configurable corners, fixed-height gapped options, and an overflow-safe top-layer listbox.
- [Autocomplete](https://balsa-ui.com/docs/components/autocomplete.md): Editable outline, surface, soft, or glass single- or multiple-value combobox with shared field sizing, configurable corners, removable selected suggestions, and an overflow-safe suggestion list.
- [Checkbox](https://balsa-ui.com/docs/components/checkbox.md): Native binary form selection with outline, surface, soft, and glass unchecked-control treatments, associated label, hint, three sizes, and configurable corners.
- [Switch](https://balsa-ui.com/docs/components/switch.md): Native boolean setting control with switch semantics, typed materials, three sizes, configurable corners, form naming, required state, and associated guidance.
- [Toggle](https://balsa-ui.com/docs/components/toggle.md): Accessible pressed-state action with typed surface, solid, outline, glass, and outline-to-solid icon treatments; semantic action colors; four sizes; and configurable corners.
- [ToggleGroup](https://balsa-ui.com/docs/components/toggle-group.md): Connected single or multiple pressed-state actions with typed options, orientation, disabled items, immutable models, and complete roving keyboard focus.
- [Collapsible](https://balsa-ui.com/docs/components/collapsible.md): Single controlled underline-default disclosure with native semantics, fully retracted inert closed content, typed materials, natural-height motion, sizing, configurable corners, disabled state, and semantic headings.
- [Accordion](https://balsa-ui.com/docs/components/accordion.md): Connected options-driven disclosure collection with single or multiple models, semantic headings, disabled items, complete vertical keyboard navigation, and shared typed materials.
- [Kbd](https://balsa-ui.com/docs/components/kbd.md): Semantic single-key and chord notation with individually rendered soft-default key caps, typed materials and sizes, configurable geometry, and accessible symbolic labels.
- [Avatar](https://balsa-ui.com/docs/components/avatar.md): Resilient labelled identity image with deterministic or custom fallback, image lifecycle state, delayed fallback, typed shapes and four sizes.
- [Pagination](https://balsa-ui.com/docs/components/pagination.md): Clamped result navigation with bounded siblings, semantic ellipses, action-label or icon-only controls, localization, sizing, geometry, and native accessibility.
- [Resizable](https://balsa-ui.com/docs/components/resizable.md): Two-panel pointer and keyboard resize group with controlled percentage, horizontal or vertical orientation, safe limits, typed materials, handle sizes, and geometry.
- [Scroll Area](https://balsa-ui.com/docs/components/scroll-area.md): Labelled native scroll viewport with typed axes, scrollbar visibility and width, optional edge fades, geometry, native events, and exposed scroll methods.
- [Preview](https://balsa-ui.com/docs/components/preview.md): Isolated natural or exact logical viewport with fit scaling, synchronized design context, accessible iframe title, and chromeless fullscreen review.
- [Carousel](https://balsa-ui.com/docs/components/carousel.md): Typed accessible Balsa-owned drag and snap collection with surface, outline, soft, and glass variants; configurable arrow and indicator placement; orientation, alignment, looping, visible slide count, empty state, and pausable autoplay.
- [Sidebar](https://balsa-ui.com/docs/components/sidebar.md): Typed grouped application navigation with active state, nested items, expanded/rail/offcanvas desktop modes, shortcut, slots, and Drawer-backed mobile behavior.
- [Attachment](https://balsa-ui.com/docs/components/attachment.md): Labelled native file selection with drag/drop, immutable single or multiple models, type/size/count validation, loading/error states, metadata, and accessible removal.
- [Table](https://balsa-ui.com/docs/components/table.md): Responsive slot-first semantic table with typed materials, density, independently configurable header and row colors, stripes, hover, gridlines, sticky header, geometry, and valid loading or empty rows.
- [Calendar](https://balsa-ui.com/docs/components/calendar.md): Locale-aware single, multiple, and range date-only selection with disabled rules, one or two months, fixed weeks, outside days, and complete grid keyboard navigation.
- [DatePicker](https://balsa-ui.com/docs/components/date-picker.md): Labelled locale-formatted single or range date field composing Calendar and collision-safe Popup with validation, disabled dates, clear action, dismissal, focus restoration, and Glassmorphism backdrop blur.
- [DataTable](https://balsa-ui.com/docs/components/data-table.md): Typed columns and rows with render slots, controlled sorting, bottom quick field and advanced filters, pagination, selection, visibility, independent header and row colors, density, loading, empty state, and responsive semantic markup.
- [Charts](https://balsa-ui.com/docs/components/charts.md): Composable responsive Unovis line, area, grouped or stacked bar, donut, and doughnut charts with contrast-safe semantic series, polished interactions, explicit states, and complete semantic table alternatives.
- [Separator](https://balsa-ui.com/docs/components/separator.md): Decorative or semantic horizontal and vertical separation with typed line styles, thicknesses, orientation, and optional aligned horizontal label content.
- [Skeleton](https://balsa-ui.com/docs/components/skeleton.md): Screen-reader-hidden text, rectangle, and circle loading placeholders with typed materials, sizing, geometry, pulse or wave motion, and reduced-motion fallback.
- [Spinner](https://balsa-ui.com/docs/components/spinner.md): Accessible indeterminate loading status with five sizes, semantic color, three speeds, hidden or visible label placement, and reduced-motion fallback.
- [Progress](https://balsa-ui.com/docs/components/progress.md): Labelled determinate or indeterminate task completion with safe value normalization, formatted value text, typed variants, semantic colors, sizing, geometry, and reduced-motion behavior.
- [Alert](https://balsa-ui.com/docs/components/alert.md): Typed inline feedback and native top-layer alert-dialog presentation with five statuses, five materials, persistent dismissal policy, focus restoration, sizing, geometry, and theme inheritance.
- [Toast](https://balsa-ui.com/docs/components/toast.md): Declarative viewport-level notification stack with primary-by-default typed items, custom icons, bounded rendering, semantic live regions, timed and sticky lifetimes, pause/resume policies, actions, Escape dismissal, position-aware transitions, responsive placement, and teleported theme inheritance.
- [Tabs](https://balsa-ui.com/docs/components/tabs.md): Keyboard-accessible local and filter-panel switching with single-axis responsive overflow, inert unslotted panels, four materials, and segmented, underline, pill, or tile layouts.
- [Code block](https://balsa-ui.com/docs/components/code-block.md): Theme-aware sized dark source and command presentation with configurable corners, text-style expansion controls, and accessible icon-only copy.
- [Dropdown](https://balsa-ui.com/docs/components/dropdown.md): Compact anchored panel for a small group of related links or actions, with typed semantic color, surface, outline, soft, and glass materials, configurable width and geometry, and safe alignment.
- [Navbar](https://balsa-ui.com/docs/components/navbar.md): Responsive semantic-color application navigation with compact item-anchored desktop menus that match its material; surface, outline, soft, and glass materials; bar, floating, and minimal layouts; desktop actions; and static, fixed, or reveal-on-scroll behavior.
- [Footer](https://balsa-ui.com/docs/components/footer.md): Responsive application footer with a linked brand, flexible grouped navigation, configurable legal content, contacts, and named social links.
- [GradientBackground](https://balsa-ui.com/docs/components/gradient-background.md): Deterministic procedural backgrounds with six pattern generators, ASCII and print-style post effects, typed presets, palette-aware colors, calm motion, lifecycle fallbacks, and still PNG capture.
- [Text3D](https://balsa-ui.com/docs/components/text-3d.md): Palette-aware and theme-aware extruded display text with finite presets, materials, environments and fonts, optional drag, wheel zoom and rotation, lifecycle fallbacks, and still PNG capture.
- [AnalyticsChartCard](https://balsa-ui.com/docs/components/analytics-chart-card.md): Trend visualization with period context and semantic delta.
- [MetricGridCard](https://balsa-ui.com/docs/components/metric-grid-card.md): Aligned operational KPIs with labels, values, and supporting detail.
- [ResourceTableCard](https://balsa-ui.com/docs/components/resource-table-card.md): Resource index with status, metadata, row selection, and creation action.
- [SettingsCard](https://balsa-ui.com/docs/components/settings-card.md): Related workspace settings with explicit reset and save actions.
- [NotificationPreferencesCard](https://balsa-ui.com/docs/components/notification-preferences-card.md): Independently controlled notification channels with concise explanations.
- [MemberAccessCard](https://balsa-ui.com/docs/components/member-access-card.md): People, identity, role, and access metadata in a scannable list.
- [NavigationMenuCard](https://balsa-ui.com/docs/components/navigation-menu-card.md): Sectioned local navigation with an explicit current destination.
- [ErrorStateCard](https://balsa-ui.com/docs/components/error-state-card.md): Recoverable failure with request context and retry action.
- [LoadingStateCard](https://balsa-ui.com/docs/components/loading-state-card.md): Stable skeleton geometry with accessible busy semantics.
- [MediaPreviewCard](https://balsa-ui.com/docs/components/media-preview-card.md): Asset preview, publication status, and replacement action.
- [PaymentMethodCard](https://balsa-ui.com/docs/components/payment-method-card.md): Selectable saved payment methods and a focused continuation action.
- [SubscriptionCard](https://balsa-ui.com/docs/components/subscription-card.md): Plan, renewal, included usage, and management action.
- [OrderSummaryCard](https://balsa-ui.com/docs/components/order-summary-card.md): Line items, calculated totals, and order confirmation.
- [OnboardingChecklistCard](https://balsa-ui.com/docs/components/onboarding-checklist-card.md): Setup tasks with progress and complete/current/future state.
- [FormProgressCard](https://balsa-ui.com/docs/components/form-progress-card.md): Linear multistep progress with current-step semantics.
- [ActivityTimelineCard](https://balsa-ui.com/docs/components/activity-timeline-card.md): Chronological actor, action, target, and time event stream.
- [CommandToolbarCard](https://balsa-ui.com/docs/components/command-toolbar-card.md): Stacked command launcher with aligned icons, descriptions, shortcuts, and full-row actions.
- [DataGridCard](https://balsa-ui.com/docs/components/data-grid-card.md): Sortable, selectable, paginated table of records with real columns.
- [SchedulePlannerCard](https://balsa-ui.com/docs/components/schedule-planner-card.md): Calendar paired with the bookable hours for the chosen day.
- [CommandPaletteCard](https://balsa-ui.com/docs/components/command-palette-card.md): Grouped command palette that reaches projects, actions, and settings from one search.
- [AssetCarouselCard](https://balsa-ui.com/docs/components/asset-carousel-card.md): Browsable run of captured assets with captions and review status.
- [SplitWorkspaceCard](https://balsa-ui.com/docs/components/split-workspace-card.md): Resizable split of a file list against the diff it selects.
- [ReleaseNotesCard](https://balsa-ui.com/docs/components/release-notes-card.md): Scrollable release history with version, date, and change notes.
- [DeviceVerificationCard](https://balsa-ui.com/docs/components/device-verification-card.md): Single-purpose one-time-code step with resend and explicit confirmation.
- [ServiceHealthCard](https://balsa-ui.com/docs/components/service-health-card.md): Half-height status strip reporting state and latency per region.
- [StorageUsageCard](https://balsa-ui.com/docs/components/storage-usage-card.md): Half-height single measurement with the bar that puts it in context.
- [InboxThreadCard](https://balsa-ui.com/docs/components/inbox-thread-card.md): Message thread with author, timing, and an inline reply.
- [FilterPanelCard](https://balsa-ui.com/docs/components/filter-panel-card.md): Grouped filters across checkboxes and a range, with reset and apply.
- [IncidentAlertCard](https://balsa-ui.com/docs/components/incident-alert-card.md): Half-height incident banner with acknowledge and open actions.
- [PlanComparisonCard](https://balsa-ui.com/docs/components/plan-comparison-card.md): Plan capabilities compared across tiers with a billing period switch.
- [ProfileFormCard](https://balsa-ui.com/docs/components/profile-form-card.md): Labelled profile fields with picture, handle, time zone, and biography.
- [UsageBreakdownCard](https://balsa-ui.com/docs/components/usage-breakdown-card.md): Stacked bars attributing billed usage to categories over time.
- [EnvironmentSwitcherCard](https://balsa-ui.com/docs/components/environment-switcher-card.md): Searchable environment picker with the current selection stated.
- [ApiKeyCard](https://balsa-ui.com/docs/components/api-key-card.md): One-time secret with copy, provenance, and revocation.
- [IntegrationListCard](https://balsa-ui.com/docs/components/integration-list-card.md): Connected services, each with the single control that governs it.
- [RunbookStepsCard](https://balsa-ui.com/docs/components/runbook-steps-card.md): Ordered procedure where only the step in hand is expanded.
- [ImageCompareCard](https://balsa-ui.com/docs/components/image-compare-card.md): Before-and-after comparison where the reader sets the split.