FAQ

General

What is Docyrus UI?

Docyrus UI is a component library built on top of shadcn/ui primitives. It provides business-grade compound components — calendars, data grids, pricing engines, resource schedulers, and more — that go beyond basic UI primitives.

Unlike traditional component libraries published to NPM, Docyrus UI uses the shadcn registry pattern: components are copied into your project as source code, giving you full ownership and customization control.

How is Docyrus UI different from shadcn/ui?

Docyrus UI includes shadcn/ui as vendor primitives. When you install a Docyrus component, its shadcn dependencies are installed automatically.

Is Docyrus UI free?

Yes. Docyrus UI is open-source. You can use it in personal and commercial projects.

Which frameworks are supported?

Web:

• Next.js 16+ (App Router)
• React 19 + Vite
• Vue 3.5 + Vite (via templates)

Native:

• React Native 0.83+ with Expo SDK 55+

Do I need to use the CLI?

The CLI (@docyrus/cli) is the recommended way to install components. It handles dependency resolution, import rewriting, and file placement automatically.

Installation

Why do components get copied into my project?

This is the shadcn pattern — instead of importing from node_modules, components live in your codebase. Benefits:

• Full control: Modify any component to match your needs
• No version lock-in: Components don't break when the library updates
• Tree-shaking: Only the components you use are in your bundle
• No runtime dependency: Your project has zero dependency on Docyrus UI at runtime

Where do components get installed?

These paths are configurable via your project's components.json.

How do I install all components at once?

# All web components
docyrus add --all web

# All native components
docyrus add --all react-native

# Specific component
docyrus add calendar
docyrus add rn-button

I'm getting peer dependency warnings

Docyrus components may require peer dependencies like motion, date-fns, or @tanstack/react-table. The CLI warns you about missing peer dependencies during installation. Install them with:

pnpm add <package-name>

Customization

How do I change the color theme?

Docyrus UI uses CSS variables with the OKLCH color space. You can:

1. Use the Theme Generator at docyrus.dev/themes to create a custom theme visually
2. Edit CSS variables directly in your globals.css — see the Web Theming Guide or Native Theming Guide

Can I use a different color palette?

Yes. The theme system supports any OKLCH color values. You can change the primary, secondary, accent, and all other colors by updating CSS variables. The Theme Generator provides preset palettes and a visual editor.

How do I override component styles?

Every component accepts a className prop for Tailwind CSS overrides:

<Button className="rounded-full px-8">Custom Button</Button>

For deeper customization, edit the component source directly — it's in your project.

Can I use CSS Modules or styled-components instead of Tailwind?

Docyrus UI is built with Tailwind CSS v4 and CVA (class-variance-authority). While you can technically replace the styling system, it would require significant refactoring. We recommend using Tailwind CSS for the best experience.

React Native

Do I need Expo?

Expo is recommended but not strictly required. Docyrus UI Native components use React Native APIs and some Expo packages. Components that require Expo-specific packages are clearly marked in the Expo section of the documentation.

Can I preview native components in a browser?

No. Native components are previewed exclusively via the Expo Preview app on a physical device or simulator. The documentation shows a QR code to open the preview in Expo Go.

How do I style native components?

Native components use Tailwind CSS via Uniwind for static styling (className prop) and the useDocyTheme() hook only for dynamic values (Ionicons colors, platform shadows, runtime lookups). See the Native Theming Guide for setup and customization.

{/* Static styling — use className */}
<View className="bg-card rounded-lg border border-border p-4">
  <Text className="text-foreground font-semibold">Card title</Text>
</View>

{/* Dynamic values only — use useDocyTheme() */}
const { colors, isDark } = useDocyTheme();
<Ionicons name="checkmark" color={colors.primary} />

Troubleshooting

Components don't render / blank screen

1. Make sure you have 'use client' directive if using Next.js App Router
2. Check that all peer dependencies are installed
3. For Tailwind v4, ensure you have @import directives in your CSS entry file

TypeScript errors after installation

Components are installed as .tsx source files. Ensure your tsconfig.json has:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

The @/ alias must resolve to your src/ directory (or wherever components are installed).

Motion animations not working

Components using motion (framer-motion) require the motion package:

pnpm add motion

If using Next.js, ensure the component has 'use client' since motion requires client-side rendering.

Icons not displaying

Docyrus uses icons from Lucide React and the Docyrus CDN (Font Awesome Brands + Huge Icons). Install Lucide:

pnpm add lucide-react

For Docyrus CDN icons, ensure your CSP (Content Security Policy) allows loading from the Docyrus CDN domain.

How do I report a bug?

Open an issue on GitHub with:

• Component name and version
• Framework and version (Next.js, Vite, Expo)
• Minimal reproduction steps
• Expected vs actual behavior