API Reference
Complete reference for all Hollows UI exports, CLI commands, and configuration options.
Hollow Component
The primary component for wrapping data-dependent UI sections. Available from each framework adapter.
tsx
import { Hollow } from 'hollows-ui/react'// import { Hollow } from 'hollows-ui/vue'// import { Hollow } from 'hollows-ui/svelte'// import { Hollow } from 'hollows-ui/angular'Props
| Prop | Type | Default | Description |
|---|---|---|---|
| name | string | required | Unique identifier that maps to the registry entry |
| empty | boolean | false | Whether to show the empty state |
| loading | boolean | false | Show a skeleton placeholder while loading |
| theme | string | Theme | inherited | Override the theme for this instance |
| illustration | string | auto | Override the illustration by name |
| heading | string | auto | Override the heading text |
| body | string | auto | Override the body text |
| ctaLabel | string | auto | Override the CTA button label |
| onCtaClick | () => void | -- | Callback when the CTA button is clicked |
| ctaHref | string | -- | Render CTA as a link instead of a button |
| className | string | -- | Additional CSS class for the container |
| children | ReactNode | -- | Content to render when not empty |
HollowsProvider
Optional context provider for setting global configuration at runtime.
tsx
import { HollowsProvider } from 'hollows-ui/react'<HollowsProvider theme="playful" locale="en"> <App /></HollowsProvider>Props
| Prop | Type | Default | Description |
|---|---|---|---|
| theme | string | Theme | 'minimal' | Global theme for all Hollow components |
| locale | string | 'en' | Active locale for copy resolution |
| registry | Registry | auto | Override the registry at runtime |
CLI Commands
hollows-ui build
Scan your codebase, classify components, and generate empty states.
| Flag | Default | Description |
|---|---|---|
| --watch | false | Watch for file changes and rebuild |
| --force | false | Ignore cache and rebuild everything |
| --config <path> | auto | Path to config file |
| --outDir <dir> | src/hollows | Output directory for generated files |
| --name <name> | all | Generate for a specific component only |
| --dry-run | false | Preview what would be generated without writing files |
| --verbose | false | Show detailed output including file paths |
hollows-ui init
Initialize a new Hollows UI configuration file.
| Flag | Description |
|---|---|
| --framework <name> | Set framework (react, vue, svelte, angular) |
| --theme <name> | Set initial theme (minimal, playful, corporate) |
hollows-ui analyze
Analyze and report on the bundle size impact of generated empty states.
hollows-ui preview
Launch a local preview server showing all generated empty states side by side.
hollows-ui list
List all detected Hollow components with file locations and classifications.
hollows-ui export-illustrations
Export built-in SVG illustrations as standalone files.
| Flag | Default | Description |
|---|---|---|
| --out <dir> | ./public/empty-states | Output directory for SVG files |
Config Options
The hollows.config.ts file accepts the following top-level options via defineConfig().
hollows.config.ts
ts
import { defineConfig } from 'hollows-ui'export default defineConfig({ // Framework detection (auto-detected if not set) framework: 'react', // 'react' | 'vue' | 'svelte' | 'angular' // Glob patterns to scan for Hollow usage include: ['src/**/*.{tsx,jsx,vue,svelte}'], exclude: ['**/*.test.*', '**/*.stories.*'], // Output directory for generated files outDir: 'src/hollows', // Theme configuration theme: 'minimal', // string | Theme object // Copy configuration copy: { tone: 'friendly', defaultLocale: 'en', locales: {}, templates: {}, }, // Responsive configuration responsive: { strategy: 'viewport', breakpoints: { sm: '640px', md: '768px', lg: '1024px', xl: '1280px' }, }, // Performance options performance: { lazyIllustrations: false, }, // Custom illustrations illustrations: { custom: [], },})| Field | Type | Default | Description |
|---|---|---|---|
| framework | string | auto | Target framework |
| include | string[] | auto | Glob patterns to scan |
| exclude | string[] | [] | Glob patterns to ignore |
| outDir | string | src/hollows | Output directory |
| theme | string | Theme | minimal | Default theme |
| copy | CopyConfig | {} | Copy/language configuration |
| responsive | ResponsiveConfig | {} | Responsive behavior config |
| performance | PerformanceConfig | {} | Performance options |
| illustrations | IllustrationConfig | {} | Custom illustration config |
Theme API
createTheme(options)
Creates a custom theme object. All properties are optional and fall back to the minimal theme defaults.
ts
import { createTheme } from 'hollows-ui'const theme = createTheme({ name: string, colors: { background: string, foreground: string, muted: string, accent: string, border: string, }, typography: { headingFont: string, bodyFont: string, headingWeight: number, headingSize: string, bodySize: string, }, spacing: { containerPadding: string, illustrationGap: string, ctaGap: string, }, borders: { radius: string, width: string, style: string, }, illustrations: { maxWidth: number, style: 'outline' | 'filled' | 'duotone', strokeWidth: number, }, cta: { borderRadius: string, padding: string, fontSize: string, fontWeight: number, },})extendTheme(base, overrides)
Extend a built-in theme with partial overrides.
ts
import { extendTheme } from 'hollows-ui'const theme = extendTheme('playful', { colors: { accent: '#6366f1' }, borders: { radius: '1rem' },})getTheme(name)
Retrieve a built-in or registered theme by name. Returns the minimal theme if the name is not found.
ts
import { getTheme } from 'hollows-ui'const theme = getTheme('playful')// Returns: { name: 'playful', colors: {...}, ... }Copy API
defineCopyTemplate(category, template)
Define a reusable copy template for a component category.
ts
import { defineCopyTemplate } from 'hollows-ui'defineCopyTemplate('inbox', { heading: 'No {{itemType}} yet', body: 'New {{itemType}} will appear here.', cta: 'Create {{itemType}}',})generateCopy(classification, tone?, hints?)
Generate copy programmatically for a given classification.
ts
import { generateCopy } from 'hollows-ui'const copy = generateCopy('inbox', 'friendly', { itemType: 'messages' })// Returns: { heading: '...', body: '...', cta: '...' }Template variables
| Variable | Description |
|---|---|
| {{name}} | The component name (from the Hollow name prop) |
| {{itemType}} | Inferred item type (e.g., "messages", "users") |
| {{category}} | The classified category (inbox, table, search, etc.) |
| {{query}} | Search query (only for search-type components) |
Illustration API
registerIllustration(name, options)
Register a custom illustration for use in Hollow components.
| Option | Type | Description |
|---|---|---|
| svg | string | SVG markup string (required) |
| variants | Record<string, string> | Theme-specific SVG variants |
| viewBox | string | Override the SVG viewBox (default: "0 0 64 64") |
getIllustration(name)
Retrieve a registered illustration by name. Returns the SVG string.
ts
import { getIllustration } from 'hollows-ui'const svg = getIllustration('empty-inbox')// Returns: '<svg viewBox="0 0 64 64" ...>...</svg>'getIllustrationForClassification(classification)
Get the illustration name that best matches a component classification.
ts
import { getIllustrationForClassification } from 'hollows-ui'const name = getIllustrationForClassification('inbox')// Returns: 'empty-inbox'Built-in illustration names
empty-inboxno-resultsempty-cartno-notificationsempty-tableno-usersempty-folderno-messagesempty-favoritesno-activityno-dataempty-calendarerror-stateUtility Types
TypeScript types exported for use in your application.
ts
import type { HollowProps, HollowsConfig, Theme, ThemeColors, ThemeTypography, ThemeSpacing, ThemeBorders, CopyTemplate, CopyTone, IllustrationStyle, RegistryEntry, Registry, ResponsiveConfig, BreakpointConfig, HollowDescriptor, ComponentClassification, ScannedComponent, AnalyzedComponent, IllustrationMeta,} from 'hollows-ui'| Type | Description |
|---|---|
| HollowProps | Props accepted by the Hollow component |
| HollowsConfig | Shape of the hollows.config.ts default export |
| Theme | Full theme object (return type of createTheme) |
| CopyTone | 'friendly' | 'professional' | 'playful' | 'minimal' |
| IllustrationStyle | 'outline' | 'filled' | 'duotone' |
| RegistryEntry | A single entry in the generated registry |
| Registry | Record<string, RegistryEntry> |
| HollowDescriptor | Full descriptor including illustration, copy, and theme |
| ComponentClassification | Classification result from the CLI scanner |
| ScannedComponent | Raw component data from the scanner |
| AnalyzedComponent | Component with classification and generated output |
| IllustrationMeta | Metadata for a registered illustration |