# FAQ
URL: /docs/guide/faq

Frequently asked questions about Docyrus UI — installation, usage, customization, and troubleshooting.

## General

### What is Docyrus UI?

Docyrus UI is a component library built on top of [shadcn/ui](https://ui.shadcn.com) 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?

| | shadcn/ui | Docyrus UI |
|---|----------|------------|
| **Focus** | UI primitives (Button, Card, Dialog) | Business components (Calendar, DataGrid, PricingEngine) |
| **Built on** | Radix UI | shadcn/ui + Radix UI + AI Elements |
| **Distribution** | Registry (copy to project) | Registry (copy to project) |
| **Styling** | Tailwind CSS | Tailwind CSS v4 |
| **Variants** | CVA | CVA (web), tailwind-variants (native) |
| **Platform** | Web only | Web + React Native |

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?

| Type | Default Location |
|------|-----------------|
| Docyrus components | `components/docyrus/` |
| shadcn primitives | `components/ui/` |
| Hooks | `hooks/` |
| Utilities | `lib/` |
| Native components | `components/docyrus-native/` |

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

### How do I install all components at once?

```bash
# 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:

```bash
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](/themes) to create a custom theme visually
2. **Edit CSS variables** directly in your `globals.css` — see the [Web Theming Guide](/docs/web/guide/theming) or [Native Theming Guide](/docs/native/guide/theming)

### 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](/themes) provides preset palettes and a visual editor.

### How do I override component styles?

Every component accepts a `className` prop for Tailwind CSS overrides:

```tsx

```

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](/docs/native/expo) 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](/docs/native/guide/theming) for setup and customization.

```tsx
{/* Static styling — use className */}

{/* Dynamic values only — use useDocyTheme() */}
const { colors, isDark } = useDocyTheme();

```

---

## 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:

```json
{
  "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:

```bash
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:

```bash
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