overview.md

Gea UI Overview

@geajs/ui is a component library for Gea that provides robust, accessible UI primitives. Interactive components are powered by Zag.js state machines — giving you full keyboard navigation, ARIA attributes, and focus management out of the box — while simple styled components offer consistent Tailwind CSS styling with variant support.

Installation

npm install @geajs/ui

@geajs/ui has a peer dependency on @geajs/core ^1.0.0. It also requires Tailwind CSS for styling — see Getting Started for the full setup instructions.

Quick Example

import { Component } from '@geajs/core'
import { Button, Dialog, Switch } from '@geajs/ui'
import '@geajs/ui/style.css'

export default class App extends Component {
  template() {
    return (
      <div>
        <Button variant="outline">Click me</Button>

        <Switch label="Dark mode" onCheckedChange={(d) => console.log(d.checked)} />

        <Dialog title="Confirm" description="Are you sure?" triggerLabel="Open">
          <Button variant="destructive">Delete</Button>
        </Dialog>
      </div>
    )
  }
}

Components at a Glance

Styled Components

Thin wrappers with Tailwind styling and variant support — no JavaScript state machines.

Component	Purpose
Button	Primary action element with variant and size props
Card	Content container with header, body, and footer slots
Input	Text input with consistent styling
Textarea	Multi-line text input
Label	Form label
Badge	Status indicator with variant support
Alert	Inline notification with title and description
Separator	Horizontal or vertical divider
Skeleton	Loading placeholder

Interactive Components (Zag-Powered)

Backed by Zag.js state machines — full keyboard navigation, ARIA attributes, and focus management.

Component	Purpose
Dialog	Modal dialog with focus trap and backdrop
Tabs	Tab panel with keyboard switching
Accordion	Expandable sections
Tooltip	Informational popup on hover
Popover	Floating content panel anchored to a trigger
Menu	Dropdown menu with typeahead
Select	Dropdown select with keyboard navigation
Combobox	Searchable dropdown
Switch	Toggle switch
Checkbox	Checkbox with indeterminate support
Radio Group	Radio button group
Slider	Range slider
Number Input	Numeric stepper
Pin Input	Verification code input
Tags Input	Tag entry field
Toggle Group	Single or multi-select toggle buttons
Progress	Progress bar
Rating Group	Star rating input
Clipboard	Copy-to-clipboard with feedback
Avatar	User avatar with fallback
Collapsible	Single expand/collapse section
Hover Card	Rich preview on hover
Pagination	Page navigation controls
File Upload	File picker with drag-and-drop
Toast	Temporary notification messages
Tree View	Hierarchical tree

Drag and Drop

A pointer-event-based drag-and-drop system that moves real DOM elements across containers.

Export	Purpose
dndManager	Singleton that manages all drag interactions
DragDropContext	Wrapper component that owns the drag lifecycle
Droppable	Drop target container
Draggable	Draggable item wrapper

Next Steps

• Getting Started — Tailwind CSS setup and configuration
• Styled Components — Button, Card, Input, and more
• Interactive Components — Dialog, Tabs, Select, and more
• Drag and Drop — Sortable lists and kanban boards
• Theming — CSS variables, dark mode, and custom styling
• Architecture — How ZagComponent bridges Zag.js and Gea