Stacks UI
Key Paths
- Core package:
storage/framework/core/ui/src/
- Components:
storage/framework/core/ui/src/components/
- UI config:
config/ui.ts (Headwind)
- STX config:
config/stx.ts
- STX engine:
node_modules/@stacksjs/stx/
- Crosswind:
node_modules/@cwcss/crosswind/
- Component types:
storage/framework/types/components.d.ts
Source Files
ui/src/
├── index.ts # Re-exports from @stacksjs/stx
├── components.ts # Component re-exports
└── components/
├── autocomplete.ts # Combobox, ComboboxInput, ComboboxOption, ComboboxOptions
├── disclosure.ts # Disclosure, DisclosureButton, DisclosurePanel
├── menu.ts # Menu, MenuButton, MenuItem, MenuItems
├── modal.ts # Dialog, DialogDescription, DialogPanel, DialogTitle
├── popover.ts # Popover, PopoverButton, PopoverPanel
├── radio-group.ts # RadioGroup, RadioGroupLabel, RadioGroupOption
├── select.ts # Combobox-based select
├── tabs.ts # Tab, TabGroup, TabList, TabPanel, TabPanels
├── toggle.ts # Switch
└── transition.ts # TransitionChild, TransitionRoot
Headless Components
import { Combobox, ComboboxInput, ComboboxOption, ComboboxOptions } from '@stacksjs/ui'
import { Dialog, DialogDescription, DialogPanel, DialogTitle } from '@stacksjs/ui'
import { Menu, MenuButton, MenuItem, MenuItems } from '@stacksjs/ui'
import { Tab, TabGroup, TabList, TabPanel, TabPanels } from '@stacksjs/ui'
import { Switch } from '@stacksjs/ui'
import { TransitionChild, TransitionRoot } from '@stacksjs/ui'
Craft Native Components
Built-in components with native HTML fallbacks:
| Component |
Fallback |
Key Props |
craft-button |
<button> |
variant (primary/secondary/outline) |
craft-text-input |
<input> |
placeholder, value, type, disabled |
craft-textarea |
<textarea> |
placeholder, value, rows |
craft-checkbox |
<input type="checkbox"> |
checked, disabled, label |
craft-select |
<select> |
value, options, placeholder |
craft-modal |
<dialog> |
open, title, closable, size |
craft-tabs |
<div> |
activeTab, tabs |
craft-table |
<table> |
columns, rows, sortable, selectable |
craft-card |
<div> |
title, subtitle, variant |
craft-alert |
<div> |
variant, title, dismissible |
craft-toast |
<div> |
variant, duration, position |
craft-tooltip |
<span> |
content, position |
craft-pagination |
<nav> |
total, page, pageSize |
craft-code-editor |
<textarea> |
value, language, theme, lineNumbers |
craft-date-picker |
<input type="date"> |
value, min, max, format |
craft-color-picker |
<input type="color"> |
value, format |
craft-badge |
<span> |
variant, size |
craft-avatar |
<div> |
src, alt, size, fallback |
craft-progress |
<div> |
value, max, variant |
craft-spinner |
<div> |
size |
craft-accordion |
<details> |
open, title |
craft-divider |
<hr> |
orientation, variant |
craft-breadcrumb |
<nav> |
items, separator |
craft-menu |
<nav> |
items, orientation |
craft-tree |
<div> |
nodes, expandable, selectable |
craft-list |
<ul> |
items, selectable |
craft-slider |
<input type="range"> |
value, min, max, step |
craft-radio |
<input type="radio"> |
checked, name, value, label |
craft-file-browser |
<div> |
path, showHidden, selectable |
Reactivity System
import { ref, namedRef, computed, watch } from '@stacksjs/stx'
const count = ref(0)
count.value = 5
const doubled = computed(() => count.value * 2)
const stop = watch(
() => count.value,
(newVal, oldVal) => console.log(`${oldVal} → ${newVal}`),
{ immediate: false }
)
stop() // cleanup
Types
interface Ref<T> { value: T | null, readonly current: T | null }
interface ComponentInstance {
id: string, element: Element | null
mountHooks: LifecycleHook[], destroyHooks: CleanupFn[], updateHooks: LifecycleHook[]
refs: Map<string, Ref<any>>, watchers: Array<{ stop: () => void }>
isMounted: boolean
}
Lifecycle Hooks
import { onMount, onDestroy, onUpdate } from '@stacksjs/stx'
// Aliases: onMounted, onUnmounted, onUpdated
onMount(() => {
console.log('mounted')
return () => console.log('cleanup') // optional
})
onDestroy(() => console.log('destroyed'))
onUpdate(() => console.log('updated'))
Dependency Injection
import { provide, inject, createInjectionKey, withInjectionScope } from '@stacksjs/stx'
const ThemeKey = createInjectionKey<string>('theme')
provide(ThemeKey, 'dark')
const theme = inject(ThemeKey) // 'dark'
const theme = inject(ThemeKey, 'light') // with default
Browser Composables
import {
useLocalStorage, useSessionStorage, useEventListener,
useClickOutside, useWindowSize, useMediaQuery,
usePrefersDark, useOnline
} from '@stacksjs/stx'
const { value, remove } = useLocalStorage('key', defaultValue)
const { width, height } = useWindowSize()
const isDark = usePrefersDark()
const isOnline = useOnline()
const cleanup = useClickOutside(elementRef, handler)
Headwind Configuration (config/ui.ts)
export default {
content: [
'./resources/**/*.{html,js,ts,jsx,tsx,stx}',
'./storage/framework/defaults/**/*.{html,js,ts,jsx,tsx,stx}',
'./storage/framework/views/**/*.{html,js,ts,jsx,tsx,stx}',
],
output: './storage/framework/assets/headwind.css',
minify: false,
} satisfies HeadwindOptions
STX Configuration (config/stx.ts)
export default {
componentsDir: 'resources/components',
layoutsDir: 'resources/layouts',
partialsDir: 'resources/partials',
} satisfies StxOptions
Full StxConfig
interface StxConfig {
enabled: boolean, debug: boolean
templatesDir?, componentsDir, partialsDir, layoutsDir?, defaultLayout?
ssr?: boolean, cache?: boolean, cachePath: string
i18n?: Partial<I18nConfig>
webComponents?: Partial<WebComponentConfig>
streaming?: Partial<StreamingConfig>
hydration?: Partial<HydrationConfig>
a11y?: Partial<A11yConfig>
seo?: Partial<SeoFeatureConfig>
animation?: Partial<AnimationConfig>
markdown?: Partial<MarkdownConfig>
pwa?: Partial<PwaConfig>
strict?: boolean | StrictModeConfig
}
Accessibility
import { checkA11y, autoFixA11y, scanA11yIssues } from '@stacksjs/stx'
const violations = await checkA11y(html, filePath)
const result = autoFixA11y(html, config)
const issues = await scanA11yIssues('./resources', { recursive: true })
interface A11yConfig {
enabled: boolean, addSrOnlyStyles: boolean
level: 'AA' | 'AAA', ignoreChecks?: string[], autoFix: boolean
}
Crosswind CSS Framework
Utility-first CSS (like Tailwind), built into Stacks:
import { buildCrosswindCSS, extractClassNames, generateCrosswindCSS } from '@stacksjs/stx'
const css = await buildCrosswindCSS(cwd)
const classNames = extractClassNames(htmlContent)
Features: theme config, 40+ variant modifiers, custom rules, shortcuts, attributify mode, bracket syntax, presets.
Gotchas
- @stacksjs/ui re-exports from @stacksjs/stx — the UI package is thin, the engine is in STX
- Craft components use native fallbacks —
preferNative: true renders plain HTML
- Refs are not Vue refs — similar API but custom reactive implementation
- Lifecycle hooks require component context — must be called within
setupComponent()
- Headwind is not Tailwind — Stacks' own CSS utility implementation
- Crosswind is the utility engine — handles class extraction, CSS generation, purging
- STX is the templating engine — handles
.stx files, SSR, streaming, hydration
- Two CSS systems coexist — Headwind (config) and Crosswind (engine)
- 150+ globally registered Vue components — no imports needed
1---2name: stacks-ui-43description: Use when working with UI in a Stacks application — components, composables, reactivity (refs/watch/computed), Craft native components, Headwind CSS, Crosswind utility framework, accessibility, or the STX templating engine. Covers @stacksjs/ui, @stacksjs/stx, and related UI tooling.4license: MIT5compatibility: Bun >= 1.3.0, TypeScript6allowed-tools: Read Edit Write Bash Grep Glob7metadata:8 source: https://skillmd.com/skills/stacksjs/stacks-ui-49---1011# Stacks UI1213## Key Paths14- Core package: `storage/framework/core/ui/src/`15- Components: `storage/framework/core/ui/src/components/`16- UI config: `config/ui.ts` (Headwind)17- STX config: `config/stx.ts`18- STX engine: `node_modules/@stacksjs/stx/`19- Crosswind: `node_modules/@cwcss/crosswind/`20- Component types: `storage/framework/types/components.d.ts`2122## Source Files23```24ui/src/25├── index.ts # Re-exports from @stacksjs/stx26├── components.ts # Component re-exports27└── components/28 ├── autocomplete.ts # Combobox, ComboboxInput, ComboboxOption, ComboboxOptions29 ├── disclosure.ts # Disclosure, DisclosureButton, DisclosurePanel30 ├── menu.ts # Menu, MenuButton, MenuItem, MenuItems31 ├── modal.ts # Dialog, DialogDescription, DialogPanel, DialogTitle32 ├── popover.ts # Popover, PopoverButton, PopoverPanel33 ├── radio-group.ts # RadioGroup, RadioGroupLabel, RadioGroupOption34 ├── select.ts # Combobox-based select35 ├── tabs.ts # Tab, TabGroup, TabList, TabPanel, TabPanels36 ├── toggle.ts # Switch37 └── transition.ts # TransitionChild, TransitionRoot38```3940## Headless Components4142```typescript43import { Combobox, ComboboxInput, ComboboxOption, ComboboxOptions } from '@stacksjs/ui'44import { Dialog, DialogDescription, DialogPanel, DialogTitle } from '@stacksjs/ui'45import { Menu, MenuButton, MenuItem, MenuItems } from '@stacksjs/ui'46import { Tab, TabGroup, TabList, TabPanel, TabPanels } from '@stacksjs/ui'47import { Switch } from '@stacksjs/ui'48import { TransitionChild, TransitionRoot } from '@stacksjs/ui'49```5051## Craft Native Components5253Built-in components with native HTML fallbacks:5455| Component | Fallback | Key Props |56|-----------|----------|-----------|57| `craft-button` | `<button>` | variant (primary/secondary/outline) |58| `craft-text-input` | `<input>` | placeholder, value, type, disabled |59| `craft-textarea` | `<textarea>` | placeholder, value, rows |60| `craft-checkbox` | `<input type="checkbox">` | checked, disabled, label |61| `craft-select` | `<select>` | value, options, placeholder |62| `craft-modal` | `<dialog>` | open, title, closable, size |63| `craft-tabs` | `<div>` | activeTab, tabs |64| `craft-table` | `<table>` | columns, rows, sortable, selectable |65| `craft-card` | `<div>` | title, subtitle, variant |66| `craft-alert` | `<div>` | variant, title, dismissible |67| `craft-toast` | `<div>` | variant, duration, position |68| `craft-tooltip` | `<span>` | content, position |69| `craft-pagination` | `<nav>` | total, page, pageSize |70| `craft-code-editor` | `<textarea>` | value, language, theme, lineNumbers |71| `craft-date-picker` | `<input type="date">` | value, min, max, format |72| `craft-color-picker` | `<input type="color">` | value, format |73| `craft-badge` | `<span>` | variant, size |74| `craft-avatar` | `<div>` | src, alt, size, fallback |75| `craft-progress` | `<div>` | value, max, variant |76| `craft-spinner` | `<div>` | size |77| `craft-accordion` | `<details>` | open, title |78| `craft-divider` | `<hr>` | orientation, variant |79| `craft-breadcrumb` | `<nav>` | items, separator |80| `craft-menu` | `<nav>` | items, orientation |81| `craft-tree` | `<div>` | nodes, expandable, selectable |82| `craft-list` | `<ul>` | items, selectable |83| `craft-slider` | `<input type="range">` | value, min, max, step |84| `craft-radio` | `<input type="radio">` | checked, name, value, label |85| `craft-file-browser` | `<div>` | path, showHidden, selectable |8687## Reactivity System8889```typescript90import { ref, namedRef, computed, watch } from '@stacksjs/stx'9192const count = ref(0)93count.value = 59495const doubled = computed(() => count.value * 2)9697const stop = watch(98 () => count.value,99 (newVal, oldVal) => console.log(`${oldVal} → ${newVal}`),100 { immediate: false }101)102stop() // cleanup103```104105### Types106```typescript107interface Ref<T> { value: T | null, readonly current: T | null }108109interface ComponentInstance {110 id: string, element: Element | null111 mountHooks: LifecycleHook[], destroyHooks: CleanupFn[], updateHooks: LifecycleHook[]112 refs: Map<string, Ref<any>>, watchers: Array<{ stop: () => void }>113 isMounted: boolean114}115```116117## Lifecycle Hooks118119```typescript120import { onMount, onDestroy, onUpdate } from '@stacksjs/stx'121// Aliases: onMounted, onUnmounted, onUpdated122123onMount(() => {124 console.log('mounted')125 return () => console.log('cleanup') // optional126})127onDestroy(() => console.log('destroyed'))128onUpdate(() => console.log('updated'))129```130131## Dependency Injection132133```typescript134import { provide, inject, createInjectionKey, withInjectionScope } from '@stacksjs/stx'135136const ThemeKey = createInjectionKey<string>('theme')137provide(ThemeKey, 'dark')138const theme = inject(ThemeKey) // 'dark'139const theme = inject(ThemeKey, 'light') // with default140```141142## Browser Composables143144```typescript145import {146 useLocalStorage, useSessionStorage, useEventListener,147 useClickOutside, useWindowSize, useMediaQuery,148 usePrefersDark, useOnline149} from '@stacksjs/stx'150151const { value, remove } = useLocalStorage('key', defaultValue)152const { width, height } = useWindowSize()153const isDark = usePrefersDark()154const isOnline = useOnline()155const cleanup = useClickOutside(elementRef, handler)156```157158## Headwind Configuration (config/ui.ts)159160```typescript161export default {162 content: [163 './resources/**/*.{html,js,ts,jsx,tsx,stx}',164 './storage/framework/defaults/**/*.{html,js,ts,jsx,tsx,stx}',165 './storage/framework/views/**/*.{html,js,ts,jsx,tsx,stx}',166 ],167 output: './storage/framework/assets/headwind.css',168 minify: false,169} satisfies HeadwindOptions170```171172## STX Configuration (config/stx.ts)173174```typescript175export default {176 componentsDir: 'resources/components',177 layoutsDir: 'resources/layouts',178 partialsDir: 'resources/partials',179} satisfies StxOptions180```181182### Full StxConfig183```typescript184interface StxConfig {185 enabled: boolean, debug: boolean186 templatesDir?, componentsDir, partialsDir, layoutsDir?, defaultLayout?187 ssr?: boolean, cache?: boolean, cachePath: string188 i18n?: Partial<I18nConfig>189 webComponents?: Partial<WebComponentConfig>190 streaming?: Partial<StreamingConfig>191 hydration?: Partial<HydrationConfig>192 a11y?: Partial<A11yConfig>193 seo?: Partial<SeoFeatureConfig>194 animation?: Partial<AnimationConfig>195 markdown?: Partial<MarkdownConfig>196 pwa?: Partial<PwaConfig>197 strict?: boolean | StrictModeConfig198}199```200201## Accessibility202203```typescript204import { checkA11y, autoFixA11y, scanA11yIssues } from '@stacksjs/stx'205206const violations = await checkA11y(html, filePath)207const result = autoFixA11y(html, config)208const issues = await scanA11yIssues('./resources', { recursive: true })209```210211```typescript212interface A11yConfig {213 enabled: boolean, addSrOnlyStyles: boolean214 level: 'AA' | 'AAA', ignoreChecks?: string[], autoFix: boolean215}216```217218## Crosswind CSS Framework219220Utility-first CSS (like Tailwind), built into Stacks:221222```typescript223import { buildCrosswindCSS, extractClassNames, generateCrosswindCSS } from '@stacksjs/stx'224225const css = await buildCrosswindCSS(cwd)226const classNames = extractClassNames(htmlContent)227```228229Features: theme config, 40+ variant modifiers, custom rules, shortcuts, attributify mode, bracket syntax, presets.230231## Gotchas232- **@stacksjs/ui re-exports from @stacksjs/stx** — the UI package is thin, the engine is in STX233- **Craft components use native fallbacks** — `preferNative: true` renders plain HTML234- **Refs are not Vue refs** — similar API but custom reactive implementation235- **Lifecycle hooks require component context** — must be called within `setupComponent()`236- **Headwind is not Tailwind** — Stacks' own CSS utility implementation237- **Crosswind is the utility engine** — handles class extraction, CSS generation, purging238- **STX is the templating engine** — handles `.stx` files, SSR, streaming, hydration239- **Two CSS systems coexist** — Headwind (config) and Crosswind (engine)240- **150+ globally registered Vue components** — no imports needed