Introduction
Spar is a headless UI component library. Zero styling opinions, maximum flexibility.
Traditional component libraries come with predefined styles and visual designs. While this works for quick prototyping, it becomes limiting when you need components that match your unique design system.
Spar takes a different approach: behavior is built in, styling stays fully customizable. Each component is a fully accessible, keyboard-navigable primitive with zero predefined styling.
Quick Start
Install Spar with npm, yarn, pnpm, or bun:
- npm
- yarn
- pnpm
- bun
npm install @turkish-technology/spar
yarn add @turkish-technology/spar
pnpm add @turkish-technology/spar
bun add @turkish-technology/spar
See the Installation Guide for requirements, framework setup, and more detailed instructions.
After installation, import a component and start building:
import { Button } from '@turkish-technology/spar';
function App() {
return <Button onClick={() => alert('Hello!')}>Click me</Button>;
}
Core Principles
Spar is built around the following principles:
- Headless Architecture: Components handle logic and accessibility, not visuals.
- Composition First: Granular component parts that work together seamlessly.
- Accessibility by Default: WCAG 2.2 AA compliant with full keyboard support.
- TypeScript Strict: Fully typed with explicit interfaces.
- Tree-Shakeable: Import only what you need with named exports.
Headless Architecture
Spar components are completely unstyled. They provide:
- Behavior Logic: State management, event handling, and user interactions.
- Accessibility Features: ARIA attributes, keyboard navigation, and screen reader support.
- Component API: A clean, predictable interface for each component.
Composition
Every component in Spar uses a compound component pattern with granular parts:
// Simple accordion example
<AccordionRoot>
<AccordionItem value="item-1">
<AccordionHeader>
<AccordionTrigger>What is Spar?</AccordionTrigger>
</AccordionHeader>
<AccordionContent>
A headless UI library with zero styling opinions.
</AccordionContent>
</AccordionItem>
</AccordionRoot>
This pattern provides:
- Flexibility: Use only the parts you need.
- Consistency: All components follow the same pattern.
- Predictability: Easy to learn and use across different components.
Accessibility
All Spar components are built with accessibility as a core requirement:
- WCAG 2.2 AA Compliant: Meets modern accessibility standards.
- Keyboard Navigation: Full keyboard support for all interactive elements.
- Screen Reader Support: Proper ARIA labels, roles, and live regions.
- Focus Management: Intelligent focus trapping and restoration.
- Automated Testing: Every component tested with jest-axe for zero accessibility violations.
Accessible components work out of the box with no extra setup.
TypeScript First
Spar is written in TypeScript with strict mode enabled:
- Full Type Safety: Every prop, state, and callback is explicitly typed.
- No
anyTypes: Strict typing throughout the codebase. - Generic Components: Type-safe components that work with application data models.
import { Button, type ButtonProps } from '@turkish-technology/spar';
// Full type safety and autocomplete
const MyButton: React.FC<ButtonProps> = props => {
return <Button {...props} />;
};
Tree-Shakeable
Spar is designed for optimal bundle size:
- Named Exports: Import only what you use.
- Zero Side Effects: No global styles or automatic registration.
- Modular Architecture: Each component is independent.
// Import only what you need
import { Button, DialogRoot, TooltipRoot } from '@turkish-technology/spar';
What's Included
Spar provides 15 production-ready headless components:
- Layout & Navigation: Accordion, Breadcrumb, Tabs
- Form Controls: Button, Checkbox, Input, Label, Radio, Select, Switch
- Overlays: Dialog, DropdownMenu, Popover, Tooltip
- Utilities: Collapsible
Plus utility hooks and TypeScript types. See all components in the Components section.
Why Headless?
Headless components separate behavior from presentation. This provides:
- Design Freedom: Style components to match any design system.
- Consistency: Use the same components across different projects with different designs.
- Maintainability: Update behavior without touching styles, and vice versa.
- Flexibility: Works with any CSS framework or styling solution.
- Performance: Include only the JavaScript needed; styling stays application-defined.
Spar handles the hard parts-state management, accessibility, keyboard navigation-so implementation effort stays focused on presentation and product-specific UI.
Next Steps
Ready to get started?
- Install Spar - Set up the library in a React app
- Browse Components - Explore all 15 available components
Community & Support
- GitHub: turkishtechnology/spar
- Issues: Report bugs or request features