# ikui
> ikui is a curated collection of reusable React components, blocks, and templates for building captivating landing pages and user-focused marketing materials. Built with React, Tailwind CSS, and Motion, it draws heavy inspiration from shadcn/ui with a magical twist. Components are copy-ready and installable via the shadcn CLI.
This file contains the full text of every ikui documentation page, concatenated for LLM consumption. For a lighter index with links, see `/llms.txt`.
---
# Introduction
ikui is a curated collection of reusable components, blocks, and templates designed to help you build captivating landing pages and user-focused marketing materials with ease.
### Philosophy
Great design is more than just aesthetics. It's a cornerstone of building trust with your audience. In a digital world, your design is often the first impression a visitor has of your brand. It’s the key to answering critical questions in their minds before they commit to engaging with your business, whether that’s signing up, making a purchase, or sharing their data.
Visitors might wonder:
- Is this brand trustworthy?
- Does this feel professional and reliable?
- Will my experience with this product be as polished as its presentation?
Poor design can signal carelessness or lack of attention to detail, leaving users hesitant. Thoughtful, high-quality design communicates confidence, reliability, and care. It suggests that if a team invests in the smallest details of their interface, they likely prioritize excellence in their product and customer experience as well.
A shining example of this philosophy in action is the landing page for Vercel, which has inspired countless users since its debut. Its clean, intentional design instantly conveys quality, making you trust the product before even trying it.
ikui draws heavy inspiration from the elegance and simplicity of shadcn/ui, reimagining it with a magical twist to help you craft delightful, trust-building user experiences.
## Community
- [Github Repository](https://github.com/WuChenDi/ikui)
- [Telegram](https://t.me/wuchendi)
- [Blog](https://wcd.pages.dev/)
- [Twitter/X](https://x.com/wuchendi96)
---
# Get Started
This guide walks you through the essential steps to seamlessly integrate ikui into your shadcn project.
## Prerequisites
ikui is built on the latest **React 19** and [Tailwind CSS v4](https://tailwindcss.com). Ensure your project is set up with these technologies before proceeding.
We recommend following the [Official shadcn/ui Installation Guide](https://ui.shadcn.com/docs/installation)
and [shadcn/create](https://ui.shadcn.com/create) setup to prepare your environment.
## Set up ikui Registry
Add the ikui registry namespace to your `components.json` and set your component library and style.
Learn more about registry config from [shadcn registry docs](https://ui.shadcn.com/docs/registry).
```json
{
...
"style": "base-nova",
...
"registries": {
"@ikui": "https://ik-ui.pages.dev/r/{name}.json"
}
}
```
## Components
You can integrate ikui using the [**shadcn CLI**](https://ui.shadcn.com/docs/cli) for automation or by manual installation for full control.
Both methods apply to everything in [Docs](/docs/introduction) and the [component catalog](/docs/components), including blocks you install with `@ikui/…`.
```bash
npx shadcn@latest add @ikui/copy-button
```
## AI-Enhanced Workflow
ikui is designed from the ground up to be **AI-friendly**, making it easier for language models to understand and modify your UI.
- **MCP**: Connect ikui through [MCP](/docs/mcp) so your IDE can find, install, and compose components for you.
- **llms.txt**: Access our [llms.txt](/llms.txt) file for a structured map of our documentation and architecture optimized for AI agents.
- **Copy Markdown**: Every page includes a **Copy Markdown** feature, allowing you to instantly feed documentation or code into your AI-driven development workflows.
---
# Components
Browse all available components in ikui. Click on a component to view its documentation.
---
# Skills
Skills give AI assistants like Claude Code project-aware knowledge of ikui. Once installed, your assistant knows how to find, install, compose, and customize ikui's media and timeline components using the correct registry, APIs, and conventions for your project.
For example, you can ask your assistant to:
- _"Add an ikui waveform player."_
- _"Build a video trimmer that exports the cut to MP4."_
- _"Drop in the audio trimmer block."_
- _"Add a before/after image compare slider."_
- _"Let users crop their avatar."_
The skill reads your project's `components.json` and pulls the **live component manifest** from the `@ikui` registry at load time, so the assistant always sees the current list of components — and resolves `@ikui/` against your real aliases and package runner — with no hardcoded inventory to fall out of date.
## Install
1. Install the skill with the [`skills`](https://github.com/WuChenDi/skills) CLI.
```bash
npx skills add wuchendi/skills --skill ikui --global
```
2. Register the `@ikui` registry in your project.
Add the following to your `components.json` so the assistant can resolve `@ikui/`:
```json
{
"registries": {
"@ikui": "https://ik-ui.pages.dev/r/{name}.json"
}
}
```
Once installed, the skill loads automatically when you ask your assistant to work with ikui, or when your project's `components.json` contains the `@ikui` registry. Learn more about skills at [skills.sh](https://skills.sh).
## What's Included
The skill gives your assistant the following knowledge:
### Live Component Manifest
On every interaction it fetches `registry.json` from the registry to get the current components and blocks — names, types, categories, and descriptions. The list is never hardcoded, so it stays accurate as ikui grows.
### Primitives vs Blocks
The single most important routing decision. **Primitives** (`registry:component`) are small, single-purpose parts — a waveform, a thumbnail strip, a timeline ruler/element/playhead, a crop box — for building your own feature. **Blocks** (`registry:block`) are finished business compositions with all the wiring done — `audio-trimmer`, `video-trimmer`, `image-cropper`. The skill reaches for a block when you name an outcome, and drops to primitives when you're assembling something custom.
### Installation via the shadcn CLI
ikui has no CLI of its own — everything installs through the shadcn CLI pointed at `@ikui`. The skill knows how to add by registry id or full URL, preview with `--dry-run`, and let `registryDependencies` (other ikui items and plain shadcn components) and npm `dependencies` resolve transitively.
### Composition Map
How the media and timeline stack fits together: `audio-waveform` → `waveform-player`; `video-thumbnail-cache` → `thumbnail-strip` → `segmented-timeline-strip`; the `timeline-ruler` / `timeline-element` / `timeline-playhead` primitives that share one `time × pixelsPerSecond × zoom` basis; and the image set (`image-compare`, `image-crop`, `particle-image`).
### Conventions
The rules ikui code follows: **Base UI** (`@base-ui/react`) — never Radix; RSC-default Next.js App Router with `"use client"` where needed; Tailwind v4 with semantic tokens and `cn()`; `lucide-react` icons and `motion` animations; imports resolved against your project's real aliases.
## How It Works
1. **Detection** — The skill activates when you ask your assistant to work with ikui, or when your project's `components.json` declares the `@ikui` registry.
2. **Live manifest** — It fetches `registry.json` and reads your `components.json`, injecting the current component list and your project config into the assistant's context.
3. **Grain routing** — It decides whether your request wants a finished **block** or the underlying **primitives**, instead of reimplementing parts that already exist.
4. **Convention enforcement** — Generated code follows ikui's rules: Base UI over Radix, `"use client"` where required, semantic Tailwind tokens, and your project's import aliases.
## Skill vs MCP
They are complementary, not alternatives:
- **[MCP](/docs/mcp)** gives your assistant a live connection to the registry — it can search and add items on demand.
- **The Skill** gives your assistant ikui-specific judgment — how the pieces compose, which conventions to honor, and whether a request wants a primitive or a block.
Use them together: MCP fetches, the Skill knows how to wire what it fetched.
## Learn More
- [Components](/docs/components) — Browse every component and block in ikui
- [MCP Server](/docs/mcp) — Connect the registry over MCP for on-demand search and install
- [WuChenDi/skills](https://github.com/WuChenDi/skills) — The skill source
- [skills.sh](https://skills.sh) — Learn more about AI skills
---
# MCP
## Installation
1. Enable [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) in your project environment. (Supports Claude Code, Cursor, etc.)
2. Add the registry to your project
Add the following to your components.json file:
```json
{
"registries": {
"@ikui": "https://ik-ui.pages.dev/r/{name}.json"
}
}
```
### Usage
You can now ask your IDE to use any ikui component. Here are some examples:
- "Add a badge component"
- "Add a blur reveal animation"
- "Add a vertical marquee of logos"
---
# LLMs
ikui is proudly hand-crafted, but we want to encourage any and all usage of ikui — even when you are building with an AI coding agent like Claude Code, Cursor, or Copilot.
Give one or more of these files to your LLM to teach it how to find, install, and compose ikui components:
## llms.txt
An index of ikui's documentation. The agent reads it to discover pages and then dives into the ones it needs. [View llms.txt](/llms.txt).
## llms-full.txt
The entire ikui documentation in a single file — every guide and component page concatenated for one-shot context. [View llms-full.txt](/llms-full.txt).
## Per-page Markdown
Every documentation page is also available as clean Markdown: append `.md` to any docs URL (for example `/docs/copy-button.md`), or use the **Copy Markdown** button in the page header to feed a single page into your AI workflow.
## MCP
Prefer a live connection? The [MCP server](/docs/mcp) lets your IDE find, install, and compose ikui components on demand.
---
# Chart
```tsx
'use client'
import { TrendingUp } from 'lucide-react'
import { Bar, BarChart, CartesianGrid, XAxis } from 'recharts'
import { Badge } from '@/components/ui/badge'
import {
Card,
CardContent,
CardDescription,
CardHeader,
CardTitle,
} from '@/components/ui/card'
import type { ChartConfig } from '@/components/ikui/chart'
import {
ChartContainer,
ChartTooltip,
ChartTooltipContent,
} from '@/components/ikui/chart'
const chartData = [
{ month: 'Jan', desktop: 300 },
{ month: 'Feb', desktop: 550 },
{ month: 'Mar', desktop: 400 },
{ month: 'Apr', desktop: 630 },
{ month: 'May', desktop: 460 },
{ month: 'Jun', desktop: 780 },
{ month: 'Jul', desktop: 390 },
{ month: 'Aug', desktop: 925 },
{ month: 'Sep', desktop: 645 },
{ month: 'Oct', desktop: 530 },
{ month: 'Nov', desktop: 700 },
{ month: 'Dec', desktop: 270 },
]
const chartConfig = {
desktop: {
label: 'Desktop',
color: 'var(--chart-1)',
},
} satisfies ChartConfig
export function Demo() {
return (
Revenue Growth
+5.2%
Monthly revenue performance tracking value.slice(0, 3)}
/>
{
return (
{value} 2024
)
}}
formatter={(value, name) => (
{chartConfig[name as keyof typeof chartConfig]
?.label || name}
${Number(value).toLocaleString()}
)}
/>
}
/>
)
}
```
Recharts-based chart primitives with theme-aware colors. `ChartContainer`
provides the responsive wrapper and maps your `ChartConfig` to CSS color
variables (`--color-`); `ChartTooltip`, `ChartTooltipContent`,
`ChartLegend`, and `ChartLegendContent` cover the surrounding chrome. Compose
the chart body itself from Recharts elements (Bar, Area, Line, Pie, Radar, …).
## Installation
```bash
npx shadcn@latest add @ikui/chart
```
## Usage
```tsx
import {
ChartContainer,
ChartTooltip,
ChartTooltipContent,
type ChartConfig,
} from "@/components/chart";
import { Bar, BarChart, XAxis } from "recharts";
```
```tsx
const chartConfig = {
desktop: { label: "Desktop", color: "var(--chart-1)" },
} satisfies ChartConfig;
} />
```
## Examples
### Multiple bars
Plot several series side by side — each `Bar` maps to a `chartConfig` key and
pulls its color from the matching `--color-` variable.
```tsx
'use client'
import { TrendingUp } from 'lucide-react'
import type { CSSProperties } from 'react'
import { Bar, BarChart, CartesianGrid, XAxis } from 'recharts'
import { Badge } from '@/components/ui/badge'
import {
Card,
CardContent,
CardDescription,
CardHeader,
CardTitle,
} from '@/components/ui/card'
import type { ChartConfig } from '@/components/ikui/chart'
import {
ChartContainer,
ChartTooltip,
ChartTooltipContent,
} from '@/components/ikui/chart'
const chartData = [
{ month: 'January', desktop: 120, mobile: 80 },
{ month: 'February', desktop: 250, mobile: 200 },
{ month: 'March', desktop: 230, mobile: 120 },
{ month: 'April', desktop: 70, mobile: 190 },
{ month: 'May', desktop: 209, mobile: 130 },
{ month: 'June', desktop: 210, mobile: 140 },
]
const chartConfig = {
desktop: {
label: 'Desktop',
color: 'var(--chart-1)',
},
mobile: {
label: 'Mobile',
color: 'var(--chart-2)',
},
} satisfies ChartConfig
export function Demo() {
return (
Market Share
+12%
Departmental performance comparison value.slice(0, 3)}
/>
{
return (
{value} 2024
)
}}
formatter={(value, name) => (
{chartConfig[name as keyof typeof chartConfig]
?.label || name}
{Number(value).toLocaleString()}
)}
/>
}
/>
)
}
```
### Gradient area
An `AreaChart` filled with an SVG `linearGradient` referencing the series
color, for a soft trend surface.
```tsx
'use client'
import { TrendingUp } from 'lucide-react'
import type { CSSProperties } from 'react'
import { Area, AreaChart, CartesianGrid, XAxis } from 'recharts'
import { Badge } from '@/components/ui/badge'
import {
Card,
CardContent,
CardDescription,
CardHeader,
CardTitle,
} from '@/components/ui/card'
import type { ChartConfig } from '@/components/ikui/chart'
import {
ChartContainer,
ChartTooltip,
ChartTooltipContent,
} from '@/components/ikui/chart'
const chartData = [
{ month: 'January', visitors: 2400 },
{ month: 'February', visitors: 2850 },
{ month: 'March', visitors: 2600 },
{ month: 'April', visitors: 3100 },
{ month: 'May', visitors: 2900 },
{ month: 'June', visitors: 3400 },
]
const chartConfig = {
visitors: {
label: 'Visitors',
color: 'var(--chart-1)',
},
} satisfies ChartConfig
export function Demo() {
return (
Website Traffic
+24.5%
Monthly unique visitor trends value.slice(0, 3)}
/>
(
{value} 2024
)}
formatter={(value, name) => (
{chartConfig[name as keyof typeof chartConfig]
?.label || name}
{Number(value).toLocaleString()}
)}
/>
}
/>
)
}
```
### Line with forecast
A `ComposedChart` layering a `Line` over a patterned `Area` to highlight a
projected trend, with a legend driven by `ChartLegendContent`.
```tsx
'use client'
import type { CSSProperties } from 'react'
import { Area, CartesianGrid, ComposedChart, Line, XAxis } from 'recharts'
import {
Card,
CardContent,
CardDescription,
CardHeader,
CardTitle,
} from '@/components/ui/card'
import type { ChartConfig } from '@/components/ikui/chart'
import {
ChartContainer,
ChartLegend,
ChartLegendContent,
ChartTooltip,
ChartTooltipContent,
} from '@/components/ikui/chart'
const chartData = [
{ month: 'January', forecast: 2600, forecastArea: 2600 },
{ month: 'February', forecast: 4200, forecastArea: 4200 },
{ month: 'March', forecast: 2400, forecastArea: 2400 },
{ month: 'April', forecast: 5000, forecastArea: 5000 },
{ month: 'May', forecast: 2800, forecastArea: 2800 },
{ month: 'June', forecast: 5800, forecastArea: 5800 },
{ month: 'July', forecast: 3200, forecastArea: 3200 },
{ month: 'August', forecast: 6200, forecastArea: 6200 },
{ month: 'September', forecast: 3800, forecastArea: 3800 },
]
const chartConfig = {
forecast: { label: 'Forecast', color: 'var(--chart-4)' },
forecastArea: { label: 'Forecast', color: 'var(--chart-4)' },
} satisfies ChartConfig
export function Demo() {
return (
Sales Forecast
Projected sales performance with trends
value.slice(0, 3)}
/>
(
{value} 2024
)}
formatter={(value, name) => (
{chartConfig[name as keyof typeof chartConfig]
?.label || name}
)
}
```
A QR code generator with rounded finder patterns and dot-style data modules.
Foreground and background default to theme tokens, so it adapts to light and
dark mode out of the box.
## Installation
```bash
npx shadcn@latest add @ikui/qr-code
```
## Usage
```tsx
import { QRCode } from "@/components/qr-code";
```
```tsx
```
## Examples
### Colors
```tsx
import { QRCode } from '@/components/ikui/qr-code'
export function Demo() {
return (
)
}
```
### Sizes
Control the rendered pixel size with `size`.
```tsx
import { QRCode } from '@/components/ikui/qr-code'
export function Demo() {
return (
)
}
```
### Quiet zone
`marginSize` adds a quiet zone around the code, measured in modules. `0` (left)
renders edge-to-edge; `4` (right) follows the spec's recommended margin.
```tsx
import { QRCode } from '@/components/ikui/qr-code'
export function Demo() {
return (
)
}
```
### Border
Toggle `bordered` to wrap the code in a themed border.
```tsx
import { QRCode } from '@/components/ikui/qr-code'
export function Demo() {
return (
)
}
```
### Error correction
Higher `errorLevel` adds redundancy (and modules), so the code survives more
damage or overlay — L, M, Q, H from left to right.
```tsx
import { QRCode } from '@/components/ikui/qr-code'
const levels = ['L', 'M', 'Q', 'H'] as const
export function Demo() {
return (
{levels.map((level) => (
))}
)
}
```
### Module shape
`dotType` and `finderType` switch between the rounded dot style (left) and a
classic square style (right) for higher scanner compatibility.
```tsx
import { QRCode } from '@/components/ikui/qr-code'
export function Demo() {
return (
)
}
```
### Status overlay
`status` overlays the code with `loading`, `expired`, or `scanned` feedback.
`expired` blurs the code and exposes a refresh action via `onRefresh`.
```tsx
'use client'
import * as React from 'react'
import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs'
import { QRCode } from '@/components/ikui/qr-code'
const states = ['active', 'loading', 'expired', 'scanned'] as const
type Status = (typeof states)[number]
export function Demo() {
const [status, setStatus] = React.useState('expired')
return (
)
}
```
### Center icon
Drop an image in the center with `icon`. Bump `errorLevel` to `"H"` so the code
stays scannable behind the logo.
```tsx
import { QRCode } from '@/components/ikui/qr-code'
export function Demo() {
return (
)
}
```
### Canvas render
Set `type="canvas"` to rasterize to a `