Basic UI components for tachUI framework
npm install @tachui/primitivesFoundation UI components for tachUI applications - the building blocks of modern web interfaces.
The @tachui/primitives package provides essential UI components that serve as the foundation for all tachUI applications. These components offer SwiftUI-inspired APIs with web-native performance and accessibility.
``bash`
npm install @tachui/primitives@0.8.0-alphaor
pnpm add @tachui/primitives@0.8.0-alpha
#### VStack
Vertically stacks child components with customizable spacing and alignment.
`typescript
import { VStack, Text } from '@tachui/primitives'
VStack({
spacing: 16,
alignment: 'leading',
children: [Text('First Item'), Text('Second Item'), Text('Third Item')],
})
`
#### HStack
Horizontally arranges child components with flexible alignment options.
`typescript
import { HStack, Button } from '@tachui/primitives'
HStack({
spacing: 12,
alignment: 'center',
children: [Button('Cancel'), Spacer(), Button('Save')],
})
`
#### ZStack
Overlays components on top of each other with alignment control.
`typescript
import { ZStack, Image, Text } from '@tachui/primitives'
ZStack({
alignment: 'bottomTrailing',
children: [
Image('/hero-background.jpg'),
Text('Overlay Text')
.modifier.padding(16)
.backgroundColor('rgba(0,0,0,0.7)')
.foregroundColor('white')
.build(),
],
})
`
#### Spacer
Flexible space that expands to fill available space in stacks.
`typescript`
HStack({
children: [
Text('Left'),
Spacer(), // Pushes content to edges
Text('Right'),
],
})
#### Divider
Visual separator line with customizable appearance.
`typescript`
VStack({
children: [Text('Section 1'), Divider(), Text('Section 2')],
})
#### Text
Displays text content with full typography control.
`typescript`
Text('Hello, tachUI!')
.modifier.font({ family: 'San Francisco', size: 18, weight: 600 })
.foregroundColor('#007AFF')
.textAlign('center')
.build()
Advanced Text Features:
`typescript
// Multiline text with line clamping
Text(longContent).modifier.lineClamp(3).wordBreak('break-word').build()
// Reactive text content
const [count, setCount] = createSignal(0)
Text(() => Count: ${count()})`
#### Image
Displays images with loading states and aspect ratio control.
`typescript`
Image('/path/to/image.jpg')
.modifier.size({ width: 200, height: 150 })
.cornerRadius(8)
.aspectRatio('cover')
.build()
Image with Assets:
`typescript
import { Assets } from '@tachui/core'
Image(Assets.profilePicture)
.modifier.size({ width: 60, height: 60 })
.cornerRadius(30)
.build()
`
#### HTML
Renders raw HTML content safely with sanitization.
` Safe HTML contenttypescript`
HTML({
content: '
sanitize: true,
})
#### Button
Interactive button component with full customization support.
`typescript`
Button('Click Me', () => {
console.log('Button clicked!')
})
.modifier.padding({ horizontal: 16, vertical: 8 })
.backgroundColor('#007AFF')
.foregroundColor('white')
.cornerRadius(8)
.build()
Button States:
`typescript`
Button('Stateful Button', handleClick)
.modifier.backgroundColor('#007AFF')
.hover({ backgroundColor: '#0051D5' })
.active({ transform: 'scale(0.95)' })
.disabled({ opacity: 0.5 })
.build()
#### Toggle
Switch/toggle component for boolean states.
`typescript
const [isEnabled, setIsEnabled] = createSignal(false)
Toggle({
isOn: () => isEnabled(),
onToggle: setIsEnabled,
})
.modifier.accentColor('#007AFF')
.build()
`
#### Picker
Selection component for choosing from multiple options.
`typescript
const options = ['Option 1', 'Option 2', 'Option 3']
const [selected, setSelected] = createSignal(options[0])
Picker({
selection: () => selected(),
onSelectionChange: setSelected,
options: options,
renderOption: option => Text(option),
})
`
#### BasicInput
Text input component with validation and formatting support.
`typescript
const [text, setText] = createSignal('')
BasicInput({
value: () => text(),
onInput: setText,
placeholder: 'Enter your name',
})
.modifier.padding(12)
.border(1, '#E5E5EA')
.cornerRadius(8)
.build()
`
Advanced Input Features:
`typescript`
BasicInput({
value: () => email(),
onInput: setEmail,
type: 'email',
validation: value => value.includes('@'),
errorMessage: 'Please enter a valid email',
})
#### BasicForm
Simple form container with validation and submission handling.
`typescript`
BasicForm({
onSubmit: data => {
console.log('Form submitted:', data)
},
children: [
BasicInput({ name: 'username', placeholder: 'Username' }),
BasicInput({ name: 'email', type: 'email', placeholder: 'Email' }),
Button('Submit', null), // null indicates form submission
],
})
`typescript
VStack({
spacing: 20,
children: [
// Header
HStack({
alignment: 'center',
children: [
Image(Assets.logo).modifier.size({ width: 40, height: 40 }).build(),
Text('My App').modifier.font({ size: 24, weight: 'bold' }).build(),
Spacer(),
Button('Menu', toggleMenu),
],
}),
// Content
VStack({
spacing: 16,
children: [
Text('Welcome to tachUI!')
.modifier.font({ size: 18 })
.textAlign('center')
.build(),
Divider(),
HStack({
spacing: 12,
children: [
Button('Get Started', startOnboarding),
Button('Learn More', openDocs)
.modifier.backgroundColor('transparent')
.foregroundColor('#007AFF')
.build(),
],
}),
],
}),
],
})
`
`typescript
VStack({
children: items.map(item =>
HStack({
spacing: { mobile: 8, desktop: 16 },
children: [
Image(item.image)
.modifier.size({ mobile: 40, desktop: 60 })
.cornerRadius({ mobile: 4, desktop: 8 })
.build(),
VStack({
alignment: 'leading',
children: [
Text(item.title)
.modifier.font({ size: { mobile: 16, desktop: 18 } })
.build(),
Text(item.description)
.modifier.font({ size: { mobile: 14, desktop: 16 } })
.opacity(0.7)
.build(),
],
}),
],
})
),
})
`
All primitive components include comprehensive accessibility support:
- ARIA Labels: Automatic and customizable ARIA attributes
- Keyboard Navigation: Full keyboard support for interactive elements
- Screen Reader Support: Optimized for screen reader compatibility
- Focus Management: Proper focus handling and visual indicators
- High Contrast: Support for high contrast modes
`typescript`
Button('Accessible Button', handleClick)
.modifier.accessibilityLabel('Save document')
.accessibilityRole('button')
.accessibilityHint('Saves the current document')
.build()
Primitives work seamlessly with the modifier system:
`typescript
import { padding, margin, backgroundColor } from '@tachui/modifiers'
Text('Styled with modifiers')
.modifier.apply(padding(16))
.apply(margin({ vertical: 8 }))
.apply(backgroundColor('#F2F2F7'))
.build()
`
- Minimal Bundle Size: Tree-shakeable components
- Efficient Rendering: Fine-grained reactivity with minimal re-renders
- Memory Efficient: Automatic cleanup and memory management
- GPU Accelerated: CSS transforms and animations when possible
Built-in validation ensures proper component usage:
`typescript
// Development warnings for common mistakes
VStack({
children: 'String', // ❌ Warning: children should be array
})
// Type-safe props
Text(123) // ❌ TypeScript error: content must be string or signal
`
`typescript
import { Show, ForEach } from '@tachui/flow-control'
VStack({
children: [
Show({
when: () => isLoading(),
children: Text('Loading...'),
}),
ForEach({
data: () => items(),
renderItem: item =>
HStack({
children: [
Text(item.name),
Spacer(),
Button('Edit', () => editItem(item)),
],
}),
}),
],
})
`
`typescript
import { NavigationLink } from '@tachui/navigation'
VStack({
children: [
NavigationLink({
destination: '/profile',
children: HStack({
children: [
Image(userAvatar),
Text(userName),
Spacer(),
Text('>').modifier.opacity(0.5).build(),
],
}),
}),
],
})
``
1. Use Semantic Components: Choose components based on meaning, not appearance
2. Leverage the Stack System: Use VStack, HStack, and ZStack for layouts instead of CSS
3. Apply Modifiers Consistently: Use the modifier chain for all styling
4. Consider Accessibility: Always provide appropriate labels and roles
5. Optimize for Performance: Use signals for reactive content, avoid object creation in renders
- Modern browsers (Chrome 88+, Firefox 85+, Safari 14+, Edge 88+)
- Progressive enhancement for older browsers
- Graceful fallback for unsupported features
This package is part of the tachUI framework and is licensed under the MPL-2.0 License.