faqs
Frequently asked questions about @gentleduck/ui.
Any question that might be related to this project you can find here. Or you can ask it on our GitHub repository.
57 styled components backed by 35 headless primitives we built ourselves - not Radix. The primitives are 50-92% smaller than Radix (Alert Dialog: 1.6 KB vs 18.6 KB). The calendar engine is ~5 KB with 4 calendar systems vs react-day-picker's ~20 KB with 1. We also ship a keyboard command system, animation tokens, atom-based state management, and a CLI with interactive merge TUI. See the full comparison with shadcn/ui.
No. The primitives are written from scratch with shared internals (Slot, Presence, Popper, focus scope) deduplicated across all 35 components. The calendar engine supports 4 calendar systems with 7 date adapters. The variant system adds memoization over class-variance-authority. The CLI has an interactive merge TUI for updating components without losing local changes. These are not wrappers around existing libraries - they are independent implementations with the same API patterns so migration is easy.
Yes. If you are on shadcn/ui, migration is a namespace swap - same component names, same compound patterns, same Tailwind classes. Both component sets coexist in the same project. Replace one component at a time with npx @gentleduck/cli add button. If you are on Radix, the primitive imports change from @radix-ui/react-dialog to @gentleduck/primitives/dialog with the same API. See the shadcn migration guide or Radix migration guide.
Run npx @gentleduck/cli init to
set up your project, then npx @gentleduck/cli add button
(or any component name) to install specific components. Import and use them like any other React component.
It's used in production. Every component is optimized for performance, accessibility, and reliability. If something doesn't work, it gets fixed ASAP.
Every component supports theme customization, style overrides, and composition patterns. Want to build your own components using our primitives? Go for it. Need to fork and modify something? Do it. Nothing is locked down.
Accessibility is part of every component. ARIA labels, keyboard navigation, screen reader support, focus management. We follow WCAG guidelines because shipping inaccessible products in 2026 is inexcusable.
Full TypeScript support with type definitions for every component. Autocomplete, type checking, and IntelliSense.
Head to our GitHub repository at github.com/gentleeduck/gentleduck . Report bugs, request features, submit pull requests, or improve documentation. We review contributions quickly and actually respond. Good ideas get implemented, bad ideas get thoughtful explanations. No corporate bureaucracy.
Real numbers: primitives are 50-92% smaller than Radix equivalents (Popover: 2.4 KB vs 19.6 KB, Dialog: 3.1 KB vs 10.6 KB). The calendar engine is ~5 KB vs react-day-picker's ~20 KB. The variant system caches results with a Map-based memoizer so repeated cva() calls in hot render paths return instantly. All packages are tree-shakeable ESM with sideEffects: false. See the full benchmarks.
Yes. Documentation, code examples, and real-world use cases. Written for developers who read docs.
MIT license. Use it for anything — personal projects, commercial products, client work.
Light, dark, and custom themes all ship in. The theming system handles dynamic switching, user preferences, and custom color schemes.
@wildduck2 is the main maintainer, backed by the @gentleduck organization. Active development, responsive to community feedback, and committed long-term.
Yes. We ship installation guides for Next.js, Vite, React Router, Astro, Laravel, TanStack Start, and manual setup. The CLI auto-detects your project type. React 18+ required.