Animated React components with an editorial feel.
Free, open-source components built with TypeScript, Tailwind CSS and Framer Motion. Install one with the CLI, or copy and paste the source.
Modus UI is not a package you import from. You own the code: add a component to your project, then change whatever you like. There's no version pinning, no wrapper API, and no waiting on a maintainer to expose a prop.
- 41 components: navigation, actions, data display, backgrounds, typography and more
- Copy-paste ready: every component is a single
.tsxfile - Themed by your tokens: components use Tailwind CSS variables (
bg-background,text-primary), so they pick up your palette - Tested on every PR: each component is rendered on desktop and mobile, with and without reduced motion
npx @modus-ui/cli add blur-textUse whichever package manager you prefer. Each component page has a tab for each:
| Package manager | Command |
|---|---|
| npm | npx @modus-ui/cli add blur-text |
| pnpm | pnpm dlx @modus-ui/cli add blur-text |
| yarn | yarn dlx @modus-ui/cli add blur-text |
| bun | bunx @modus-ui/cli add blur-text |
The CLI writes the component into your project and lists the npm packages it needs. Every component page shows its own command.
To copy and paste instead, open the Code tab on any component page and save the file as components/ui/<name>.tsx. Components import cn() from @/lib/utils:
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}Signing in with Google is optional and only needed to favorite a component or comment on it. The
site itself, the CLI and the MCP server stay anonymous. Data lives in the modus_ui schema of the
shared side-project Supabase Postgres. Set these in .env (gitignored; copy the two URLs from the
Supabase dashboard, Connect):
# Transaction pooler (port 6543): runtime queries
DATABASE_URL="postgresql://postgres.<project-ref>:<password>@aws-0-<region>.pooler.supabase.com:6543/postgres?pgbouncer=true&schema=modus_ui"
# Session pooler (port 5432): Prisma migrations
DIRECT_URL="postgresql://postgres.<project-ref>:<password>@aws-0-<region>.pooler.supabase.com:5432/postgres?schema=modus_ui"
BETTER_AUTH_SECRET=<openssl rand -hex 32>
BETTER_AUTH_URL=http://localhost:3000
GOOGLE_OAUTH_CLIENT_ID=...
GOOGLE_OAUTH_CLIENT_SECRET=...
Add <BETTER_AUTH_URL>/api/auth/callback/google as an authorised redirect URI on the Google OAuth
client (localhost and the production domain), then apply the schema with pnpm db:migrate.
The MCP server lets your agent search the catalogue, read a component's real props and source, and get its install command:
claude mcp add modus-ui -- npx -y @modus-ui/mcpFor Cursor, Windsurf or VS Code setup, see packages/mcp. The docs are also published as plain markdown so agents like Claude Code, Cursor or Codex can read them directly:
/llms.txt: index of every component with a one-line description/llms-full.txt: every component's docs and full source in one file/components/<name>.md, e.g./components/blur-text.md: one component's install command, usage and source
| Category | Components |
|---|---|
| Navigation | Liquid Tabs, Flowing Menu, Morphing Navbar, Floating Dock, Notch Footer, Process Stepper |
| Actions | Magnet, Magic Button, Animated Button, Pulse Button |
| Data Display | Bounce Cards, Masonry Grid, Animated List, Kinetic Carousel, Expandable Showcase, Focus Card, Rotating Card, Tilt Card |
| Backgrounds | Cursor Grid, Waves, Letter Glitch, Aurora Background, Circuit Background, Grid Motion |
| Typography | Scroll Velocity, Text Pressure, True Focus, Gradient Text, Blur Text, Split Text, Decrypted Text, Shimmer Text, Floating Text |
| Components | Scratch to Reveal, Stack, Star Border, Tilted Card, Pixel Card, Click Spark, Spotlight Card, Border Glow |
| React Native · Data | Swipe Actions, Swipe Deck, Fold Panel, Snap Carousel, Parallax Header, Roll Number, Drag List, Marquee Ticker, Avatar Stack, Expand Card, Chat Bubble, Setting List, Data Table, Timeline List, Rating Histogram, Contact Index, Poll Bars, Expandable Text, Task Checklist, Spark Bars, Compare Slider |
| React Native · Overlays | Snap Sheet, Long Press Menu, Action Tray, Confirm Dialog, Tip Popover |
| React Native · Navigation | Glide Segments, Bubble Tab Bar, Intro Pager, Step Tracker, Tab Pager, Side Drawer, Page Dots |
| React Native · Buttons | Fan Menu, Slide Confirm, Reaction Bar, Action Button, Resend Button, Extended FAB, Like Button, Hold Confirm |
| React Native · Inputs | Pin Pad, Slide Switch, Star Rating, Value Slider, Expand Search, Calendar Strip, Chip Input, Choice Chips, Hold Stepper, Code Boxes, Hue Picker, Wheel Picker, Range Slider, Tick Box, Suggest Input, Float Field, Month Grid, Composer Bar, Radio Group, Mode Toggle, Select Grid, Card Field, Step Slider, Cart Quantity, Password Field, Mood Picker, Swatch Picker, Select Menu |
| React Native · Feedback | Flick Toast, Notice Banner, Count Badge, Live Dot, Pull Refresh, Empty State, Undo Snackbar |
| React Native · Progress | Shimmer Block, Typing Dots, Stripe Progress, Ring Meter, Story Bars, Spin Loader, Wave Bars, Password Meter, Countdown Timer, Gauge Meter, Battery Meter |
| Hooks | useColorScheme, useKeyboardHeight, useHaptics, useReduceMotion, useDebouncedValue |
| Providers | ModeProvider, ThemeProvider |
| Theme | Colors, Globals |
| Hooks | useColorScheme, useKeyboardHeight, useHaptics, useReduceMotion, useDebouncedValue |
| Providers | ModeProvider, ThemeProvider |
| Theme | Colors, Globals |
React Native components are Expo files that import only react-native, so they need no extra packages. Install them the same way (npx @modus-ui/cli add swipe-actions); the docs preview them live in the browser through react-native-web.
Run the site locally and open /components. Each component page has:
- A live preview with a restart button, plus a full-screen standalone preview at
/preview/<name> - The full source, with syntax highlighting and copy to clipboard
- CLI and manual installation steps
- Usage examples and a props table
Requires Node 20+ and pnpm. The CLI and MCP server live in packages/cli and packages/mcp as a pnpm workspace.
git clone https://github.com/kasimkazmi/Modus-UI.git
cd Modus-UI
pnpm install
pnpm devThe site runs at http://localhost:3000.
| Script | What it does |
|---|---|
pnpm dev |
Start the dev server |
pnpm build |
Build the production site, then regenerate public/registry/ |
pnpm start |
Serve the production build |
pnpm lint |
ESLint |
pnpm typecheck |
TypeScript, no emit |
pnpm format |
Prettier, with Tailwind class sorting (format:check to verify) |
pnpm test |
Vitest: registry integrity and coding-standard checks |
pnpm test:e2e |
Playwright: builds, serves, then runs desktop Chrome and Pixel 7 |
pnpm check |
Lint, typecheck and unit tests in one go |
pnpm build:registry |
Write each component's JSON to public/registry/ for the CLI |
pnpm new:component |
Scaffold and register a component (--name, --category, --title) |
pnpm release |
Interactive release of @modus-ui/cli / @modus-ui/mcp: bump, build, test, tag, then publish via GitHub Actions (npm trusted publishing) or locally |
A pre-commit hook runs ESLint and Prettier on staged files.
CI (.github/workflows/ci.yml) runs three jobs on every pull request:
- Lint, typecheck & test:
tests/registry.test.tsfails if a component is missing a demo or a doc, isn't wired into every page that lists it, or imports a package its registry entry doesn't declare.tests/conventions.test.tsenforces the rules inAGENTS.md. - Build & registry: the registry build fails on any broken component, and the committed
public/registry/has to match what the build produces. - End-to-end:
tests/e2e/components.spec.tsopens every docs page and standalone preview. It fails on any console error, hydration mismatch or failed request, and when a preview's content never becomes visible, with motion on or reduced.
src/
├── registry/
│ ├── index.ts # Registry: the single source of truth for every component
│ ├── demos.ts # Demo for each component, type-checked against the registry
│ ├── <name>.tsx # The component users install
│ └── <name>-demo.tsx # The demo shown in docs and previews
├── content/docs/<name>.mdx # Documentation page for each component
├── app/
│ ├── docs/ # Docs layout, sidebar, index and [slug] pages
│ └── preview/[name]/ # Full-screen standalone previews
├── components/ # Site UI: preview tabs, code block, copy button
└── lib/ # Registry loader, MDX loader, cn()
scripts/build-registry.ts # Generates public/registry/*.json
tests/ # Vitest unit tests and Playwright e2e
Contributions are welcome. Check the open issues first, then:
- Fork the repo and create a branch named
feat/<component-name>orfix/<what>. - Follow
COMPONENTS_GUIDE.mdfor file layout, design standards and the MDX template, andAGENTS.mdfor coding rules (TypeScript, Tailwind variables,framer-motion,cn()). - Scaffold it with
pnpm new:component --name flip-clock --category Typography, which writes the component, demo and doc and registers them. To do it by hand, register the component insrc/registry/index.ts(name, title, category) and its demo insrc/registry/demos.ts. The sidebar, components index and previews are generated from these, andpnpm typecheck/pnpm testtell you if anything is missing. - Run
pnpm checkandpnpm test:e2ebefore opening a pull request. Include a screenshot or recording of the component.
Some components take inspiration from publicly available work, including React Bits and Magic UI, and are rewritten in TypeScript with Tailwind and Framer Motion. If you recognize your work, open an issue to request credit.
Kasim Kazmi: creator and maintainer