upstream/upstream-shadcn-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

snapshot of https://github.com/shadcn-ui/ui.git (main, 2026-09-15; blobs > 131072B omitted)
All checks were successful
Release / Create Version PR or Publish Stable Release (push) Has been skipped
Details
Release / Publish Prerelease to NPM (push) Has been skipped
Details
Monitor Registries / Monitor registry health (push) Has been skipped
Details

Browse Source
This commit is contained in:
upstream-mirror
2026-09-15 22:44:43 +05:00
commit 1416db152c
5727 changed files with 630238 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

482
apps/v4/content/docs/changelog/2023-06-new-cli.mdx Normal file
View File

@@ -0,0 +1,482 @@
---
title: June 2023 - New CLI, Styles and more
description: Complete CLI rewrite with new styles, theming options, and more.
date: 2023-06-22
---
I have a lot of updates to share with you today:
- [**New CLI**](#new-cli) - Rewrote the CLI from scratch. You can now add components, dependencies and configure import paths.
- [**Theming**](#theming-with-css-variables-or-tailwind-colors) - Choose between using CSS variables or Tailwind CSS utility classes for theming.
- [**Base color**](#base-color) - Configure the base color for your project. This will be used to generate the default color palette for your components.
- [**React Server Components**](#react-server-components) - Opt out of using React Server Components. The CLI will automatically append or remove the `use client` directive.
- [**Styles**](#styles) - Introducing a new concept called _Style_. A style comes with its own set of components, animations, icons and more.
- [**Exit animations**](#exit-animations) - Added exit animations to all components.
- [**Other updates**](#other-updates) - New `icon` button size, updated `sheet` component and more.
- [**Updating your project**](#updating-your-project) - How to update your project to get the latest changes.
---
### New CLI
I've been working on a new CLI for the past few weeks. It's a complete rewrite. It comes with a lot of new features and improvements.
### `init`
```bash
npx shadcn@latest init
```
When you run the `init` command, you will be asked a few questions to configure `components.json`:
```txt showLineNumbers
Which style would you like to use? › Default
Which color would you like to use as base color? › Slate
Where is your global CSS file? › › app/globals.css
Do you want to use CSS variables for colors? › no / yes
Where is your tailwind.config.js located? › tailwind.config.js
Configure the import alias for components: › @/components
Configure the import alias for utils: › @/lib/utils
Are you using React Server Components? › no / yes
```
This file contains all the information about your components: where to install them, the import paths, how they are styled...etc.
You can use this file to change the import path of a component, set a baseColor or change the styling method.
```json title="components.json" showLineNumbers
{
"style": "default",
"tailwind": {
"config": "tailwind.config.ts",
"css": "src/app/globals.css",
"baseColor": "zinc",
"cssVariables": true
},
"rsc": false,
"aliases": {
"utils": "~/lib/utils",
"components": "~/components"
}
}
```
This means you can now use the CLI with any directory structure including `src` and `app` directories.
### `add`
```bash
npx shadcn@latest add
```
The `add` command is now much more capable. You can now add UI components but also import more complex components (coming soon).
The CLI will automatically resolve all components and dependencies, format them based on your custom config and add them to your project.
### `diff` (experimental)
```bash
npx shadcn diff
```
We're also introducing a new `diff` command to help you keep track of upstream updates.
You can use this command to see what has changed in the upstream repository and update your project accordingly.
Run the `diff` command to get a list of components that have updates available:
```bash
npx shadcn diff
```
```txt
The following components have updates available:
- button
- /path/to/my-app/components/ui/button.tsx
- toast
- /path/to/my-app/components/ui/use-toast.ts
- /path/to/my-app/components/ui/toaster.tsx
```
Then run `diff [component]` to see the changes:
```bash
npx shadcn diff alert
```
```diff /pl-12/
const alertVariants = cva(
- "relative w-full rounded-lg border",
+ "relative w-full pl-12 rounded-lg border"
)
```
---
### Theming with CSS Variables or Tailwind Colors
You can choose between using CSS variables or Tailwind CSS utility classes for theming.
When you add new components, the CLI will automatically use the correct theming methods based on your `components.json` configuration.
#### Utility classes
```tsx /bg-zinc-950/ /text-zinc-50/ /dark:bg-white/ /dark:text-zinc-950/
<div className="bg-zinc-950 dark:bg-white" />
```
To use utility classes for theming set `tailwind.cssVariables` to `false` in your `components.json` file.
```json {6} title="components.json" showLineNumbers
{
"tailwind": {
"config": "tailwind.config.js",
"css": "app/globals.css",
"baseColor": "slate",
"cssVariables": false
}
}
```
#### CSS Variables
```tsx /bg-background/ /text-foreground/
<div className="bg-background text-foreground" />
```
To use CSS variables classes for theming set `tailwind.cssVariables` to `true` in your `components.json` file.
```json {6} title="components.json" showLineNumbers
{
"tailwind": {
"config": "tailwind.config.js",
"css": "app/globals.css",
"baseColor": "slate",
"cssVariables": true
}
}
```
---
### Base color
You can now configure the base color for your project. This will be used to generate the default color palette for your components.
```json {5} title="components.json" showLineNumbers
{
"tailwind": {
"config": "tailwind.config.js",
"css": "app/globals.css",
"baseColor": "zinc",
"cssVariables": false
}
}
```
Choose between `gray`, `neutral`, `slate`, `stone` or `zinc`.
If you have `cssVariables` set to `true`, we will set the base colors as CSS variables in your `globals.css` file. If you have `cssVariables` set to `false`, we will inline the Tailwind CSS utility classes in your components.
---
### React Server Components
If you're using a framework that does not support React Server Components, you can now opt out by setting `rsc` to `false`. We will automatically append or remove the `use client` directive when adding components.
```json title="components.json" showLineNumbers
{
"rsc": false
}
```
---
### Styles
We are introducing a new concept called _Style_.
_You can think of style as the visual foundation: shapes, icons, animations & typography._ A style comes with its own set of components, animations, icons and more.
We are shipping two styles: `default` and `new-york` (with more coming soon).
<Image
src="/images/style.jpg"
width="716"
height="402"
alt="Default vs New York style"
className="mt-6 overflow-hidden rounded-2xl border"
/>
The `default` style is the one you are used to. It's the one we've been using since the beginning of this project. It uses `lucide-react` for icons and `tailwindcss-animate` for animations.
The `new-york` style is a new style. It ships with smaller buttons, cards with shadows and a new set of icons from [Radix Icons](https://icons.radix-ui.com).
When you run the `init` command, you will be asked which style you would like to use. This is saved in your `components.json` file.
```json title="components.json" showLineNumbers
{
"style": "new-york"
}
```
### Theming
Start with a style as the base then theme using CSS variables or Tailwind CSS utility classes to completely change the look of your components.
<Image
src="/images/style-with-theming.jpg"
width="716"
height="402"
alt="Style with theming"
className="mt-6 overflow-hidden rounded-2xl border"
/>
---
### Exit animations
I added exit animations to all components. Click on the combobox below to see the subtle exit animation.
<ComponentPreview
styleName="new-york-v4"
name="combobox-demo"
className="[&_.preview]:items-start"
/>
The animations can be customized using utility classes.
---
### Other updates
### Button
- Added a new button size `icon`:
<ComponentPreview styleName="new-york-v4" name="button-icon" />
### Sheet
- Renamed `position` to `side` to match the other elements.
<ComponentPreview styleName="new-york-v4" name="sheet-side" />
- Removed the `size` props. Use `className="w-[200px] md:w-[450px]"` for responsive sizing.
---
### Updating your project
Since we follow a copy and paste approach, you will need to manually update your project to get the latest changes.
<Callout className="mt-4">
Note: we are working on a [`diff`](#diff-experimental) command to help you
keep track of upstream updates.
</Callout>
<Steps>
### Add `components.json`
Creating a `components.json` file at the root:
```json title="components.json" showLineNumbers
{
"style": "default",
"rsc": true,
"tailwind": {
"config": "tailwind.config.js",
"css": "app/globals.css",
"baseColor": "slate",
"cssVariables": true
},
"aliases": {
"components": "@/components",
"utils": "@/lib/utils"
}
}
```
Update the values for `tailwind.css` and `aliases` to match your project structure.
### Button
Add the `icon` size to the `buttonVariants`:
```tsx {7} title="components/ui/button.tsx" showLineNumbers
const buttonVariants = cva({
variants: {
size: {
default: "h-10 px-4 py-2",
sm: "h-9 rounded-md px-3",
lg: "h-11 rounded-md px-8",
icon: "h-10 w-10",
},
},
})
```
### Sheet
1. Replace the content of `sheet.tsx` with the following:
```tsx title="components/ui/sheet.tsx" showLineNumbers
"use client"
import * as React from "react"
import * as SheetPrimitive from "@radix-ui/react-dialog"
import { cva, type VariantProps } from "class-variance-authority"
import { X } from "lucide-react"
import { cn } from "@/lib/utils"
const Sheet = SheetPrimitive.Root
const SheetTrigger = SheetPrimitive.Trigger
const SheetClose = SheetPrimitive.Close
const SheetPortal = ({
className,
...props
}: SheetPrimitive.DialogPortalProps) => (
<SheetPrimitive.Portal className={cn(className)} {...props} />
)
SheetPortal.displayName = SheetPrimitive.Portal.displayName
const SheetOverlay = React.forwardRef<
React.ElementRef<typeof SheetPrimitive.Overlay>,
React.ComponentPropsWithoutRef<typeof SheetPrimitive.Overlay>
>(({ className, ...props }, ref) => (
<SheetPrimitive.Overlay
className={cn(
"fixed inset-0 z-50 bg-background/80 backdrop-blur-sm data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:animate-in data-[state=open]:fade-in-0",
className
)}
{...props}
ref={ref}
/>
))
SheetOverlay.displayName = SheetPrimitive.Overlay.displayName
const sheetVariants = cva(
"fixed z-50 gap-4 bg-background p-6 shadow-lg transition ease-in-out data-[state=closed]:animate-out data-[state=closed]:duration-300 data-[state=open]:animate-in data-[state=open]:duration-500",
{
variants: {
side: {
top: "inset-x-0 top-0 border-b data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top",
bottom:
"inset-x-0 bottom-0 border-t data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom",
left: "inset-y-0 left-0 h-full w-3/4 border-r data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left sm:max-w-sm",
right:
"inset-y-0 right-0 h-full w-3/4 border-l data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right sm:max-w-sm",
},
},
defaultVariants: {
side: "right",
},
}
)
interface SheetContentProps
extends React.ComponentPropsWithoutRef<typeof SheetPrimitive.Content>,
VariantProps<typeof sheetVariants> {}
const SheetContent = React.forwardRef<
React.ElementRef<typeof SheetPrimitive.Content>,
SheetContentProps
>(({ side = "right", className, children, ...props }, ref) => (
<SheetPortal>
<SheetOverlay />
<SheetPrimitive.Content
ref={ref}
className={cn(sheetVariants({ side }), className)}
{...props}
>
{children}
<SheetPrimitive.Close className="absolute top-4 right-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:ring-2 focus:ring-ring focus:ring-offset-2 focus:outline-none disabled:pointer-events-none data-[state=open]:bg-secondary">
<X className="h-4 w-4" />
<span className="sr-only">Close</span>
</SheetPrimitive.Close>
</SheetPrimitive.Content>
</SheetPortal>
))
SheetContent.displayName = SheetPrimitive.Content.displayName
const SheetHeader = ({
className,
...props
}: React.HTMLAttributes<HTMLDivElement>) => (
<div
className={cn(
"flex flex-col space-y-2 text-center sm:text-left",
className
)}
{...props}
/>
)
SheetHeader.displayName = "SheetHeader"
const SheetFooter = ({
className,
...props
}: React.HTMLAttributes<HTMLDivElement>) => (
<div
className={cn(
"flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2",
className
)}
{...props}
/>
)
SheetFooter.displayName = "SheetFooter"
const SheetTitle = React.forwardRef<
React.ElementRef<typeof SheetPrimitive.Title>,
React.ComponentPropsWithoutRef<typeof SheetPrimitive.Title>
>(({ className, ...props }, ref) => (
<SheetPrimitive.Title
ref={ref}
className={cn("text-lg font-semibold text-foreground", className)}
{...props}
/>
))
SheetTitle.displayName = SheetPrimitive.Title.displayName
const SheetDescription = React.forwardRef<
React.ElementRef<typeof SheetPrimitive.Description>,
React.ComponentPropsWithoutRef<typeof SheetPrimitive.Description>
>(({ className, ...props }, ref) => (
<SheetPrimitive.Description
ref={ref}
className={cn("text-sm text-muted-foreground", className)}
{...props}
/>
))
SheetDescription.displayName = SheetPrimitive.Description.displayName
export {
Sheet,
SheetTrigger,
SheetClose,
SheetContent,
SheetHeader,
SheetFooter,
SheetTitle,
SheetDescription,
}
```
2. Rename `position` to `side`
```diff /position/ /side/
- <Sheet position="right" />
+ <Sheet side="right" />
```
</Steps>
### Thank you
I'd like to thank everyone who has been using this project, providing feedback and contributing to it. I really appreciate it. Thank you.

45
apps/v4/content/docs/changelog/2023-07-javascript.mdx Normal file
View File

@@ -0,0 +1,45 @@
---
title: July 2023 - JavaScript
description: JavaScript version of components available via the CLI.
date: 2023-07-04
---
This project and the components are written in TypeScript. **We recommend using TypeScript for your project as well**.
However we provide a JavaScript version of the components, available via the [cli](/docs/cli).
```txt
Would you like to use TypeScript (recommended)? no
```
To opt-out of TypeScript, you can use the `tsx` flag in your `components.json` file.
```json {10} title="components.json" showLineNumbers
{
"style": "default",
"tailwind": {
"config": "tailwind.config.js",
"css": "src/app/globals.css",
"baseColor": "zinc",
"cssVariables": true
},
"rsc": false,
"tsx": false,
"aliases": {
"utils": "~/lib/utils",
"components": "~/components"
}
}
```
To configure import aliases, you can use the following `jsconfig.json`:
```json {4} title="jsconfig.json" showLineNumbers
{
"compilerOptions": {
"paths": {
"@/*": ["./*"]
}
}
}
```

68
apps/v4/content/docs/changelog/2023-12-new-components.mdx Normal file
View File

@@ -0,0 +1,68 @@
---
title: December 2023 - New Components
description: Carousel, Drawer, Pagination, Resizable, Sonner, and CLI updates.
date: 2023-12-22
---
We've added new components to shadcn/ui and made a lot of improvements to the CLI.
Here's a quick overview of what's new:
- [**Carousel**](#carousel) - A carousel component with motion, swipe gestures and keyboard support.
- [**Drawer**](#drawer) - A drawer component that looks amazing on mobile.
- [**Pagination**](#pagination) - A pagination component with page navigation, previous and next buttons.
- [**Resizable**](#resizable) - A resizable component for building resizable panel groups and layouts.
- [**Sonner**](#sonner) - The last toast component you'll ever need.
- [**CLI updates**](#cli-updates) - Support for custom **Tailwind prefix** and `tailwind.config.ts`.
### Carousel
We've added a fully featured carousel component with motion, swipe gestures and keyboard support. Built on top of [Embla Carousel](https://www.embla-carousel.com).
It has support for infinite looping, autoplay, vertical orientation, and more.
<ComponentPreview styleName="new-york-v4" name="carousel-demo" />
### Drawer
Oh the drawer component. Built on top of [Vaul](https://github.com/emilkowalski/vaul) by [emilkowalski](https://twitter.com/emilkowalski).
Try opening the following drawer on mobile. It looks amazing!
<ComponentPreview styleName="new-york-v4" name="drawer-demo" />
### Pagination
We've added a pagination component with page navigation, previous and next buttons. Simple, flexible and works with your framework's `<Link />` component.
<ComponentPreview styleName="new-york-v4" name="pagination-demo" />
### Resizable
Build resizable panel groups and layouts with this `<Resizable />` component.
<ComponentPreview styleName="new-york-v4" name="resizable-demo-with-handle" />
`<Resizable />` is built using [react-resizable-panels](https://github.com/bvaughn/react-resizable-panels) by [bvaughn](https://github.com/bvaughn). It has support for mouse, touch and keyboard.
### Sonner
Another one by [emilkowalski](https://twitter.com/emilkowalski). The last toast component you'll ever need. Sonner is now available in shadcn/ui.
<ComponentPreview styleName="new-york-v4" name="sonner-demo" />
### CLI updates
This has been one of the most requested features. You can now configure a custom Tailwind prefix and the cli will automatically prefix your utility classes when adding components.
This means you can now easily add shadcn/ui components to existing projects like Docusaurus, Nextra...etc. A drop-in for your existing design system with no conflict.
```tsx /tw-/
<AlertDialog className="tw-grid tw-gap-4 tw-border tw-bg-background tw-shadow-lg" />
```
It works with `cn`, `cva` and CSS variables.
The cli can now also detect `tailwind.config.ts` and add the TypeScript version of the config for you.
That's it. Happy Holidays.

99
apps/v4/content/docs/changelog/2024-03-blocks.mdx Normal file
View File

@@ -0,0 +1,99 @@
---
title: March 2024 - Introducing Blocks
description: Ready-made components for dashboards and authentication pages.
date: 2024-03-22
---
One of the most requested features since launch has been layouts: admin dashboards with sidebar, marketing page sections, cards and more.
**Today, we're launching [Blocks](/blocks).**
<a href="/blocks">
<Image
src="/images/dashboard-1.jpg"
width="716"
height="430"
alt="Admin dashboard"
className="mt-6 w-full overflow-hidden rounded-2xl border dark:hidden"
/>
<Image
src="/images/dashboard-1-dark.jpg"
width="716"
height="430"
alt="Admin dashboard"
className="mt-6 hidden w-full overflow-hidden rounded-2xl border shadow-sm dark:block"
/>
<span className="sr-only">View the blocks library</span>
</a>
Blocks are ready-made components that you can use to build your apps. They are fully responsive, accessible, and composable, meaning they are built using the same principles as the rest of the components in shadcn/ui.
We're starting with dashboard layouts and authentication pages, with plans to add more blocks in the coming weeks.
### Open Source
Blocks are open source. You can find the source on GitHub. Use them in your projects, customize them and contribute back.
<a href="/blocks">
<Image
src="/images/dashboard-2.jpg"
width="716"
height="420"
alt="AI Playground"
className="mt-6 w-full overflow-hidden rounded-2xl border dark:hidden"
/>
<Image
src="/images/dashboard-2-dark.jpg"
width="716"
height="420"
alt="AI Playground"
className="mt-6 hidden w-full overflow-hidden rounded-2xl border shadow-sm dark:block"
/>
<span className="sr-only">View the blocks library</span>
</a>
### Request a Block
We're also introducing a "Request a Block" feature. If there's a specific block you'd like to see, simply create a request on GitHub and the community can upvote and build it.
<a href="/blocks">
<Image
src="/images/dashboard-3.jpg"
width="716"
height="420"
alt="Settings Page"
className="mt-6 w-full overflow-hidden rounded-2xl border dark:hidden"
/>
<Image
src="/images/dashboard-3-dark.jpg"
width="716"
height="420"
alt="Settings Page"
className="mt-6 hidden w-full overflow-hidden rounded-2xl border shadow-sm dark:block"
/>
<span className="sr-only">View the blocks library</span>
</a>
### v0
If you have a [v0](https://v0.dev) account, you can use the **Edit in v0** feature to open the code on v0 for prompting and further generation.
<div className="mt-6 flex aspect-video w-full items-center justify-center overflow-hidden rounded-2xl border bg-background shadow-sm">
<svg
viewBox="0 0 40 20"
fill="none"
xmlns="http://www.w3.org/2000/svg"
className="h-40 w-40 text-foreground"
>
<path
d="M23.3919 0H32.9188C36.7819 0 39.9136 3.13165 39.9136 6.99475V16.0805H36.0006V6.99475C36.0006 6.90167 35.9969 6.80925 35.9898 6.71766L26.4628 16.079C26.4949 16.08 26.5272 16.0805 26.5595 16.0805H36.0006V19.7762H26.5595C22.6964 19.7762 19.4788 16.6139 19.4788 12.7508V3.68923H23.3919V12.7508C23.3919 12.9253 23.4054 13.0977 23.4316 13.2668L33.1682 3.6995C33.0861 3.6927 33.003 3.68923 32.9188 3.68923H23.3919V0Z"
fill="currentColor"
></path>
<path
d="M13.7688 19.0956L0 3.68759H5.53933L13.6231 12.7337V3.68759H17.7535V17.5746C17.7535 19.6705 15.1654 20.6584 13.7688 19.0956Z"
fill="currentColor"
></path>
</svg>
</div>
That's it. _Looking forward to seeing what you build with Blocks_.

25
apps/v4/content/docs/changelog/2024-03-breadcrumb-otp.mdx Normal file
View File

@@ -0,0 +1,25 @@
---
title: March 2024 - Breadcrumb and Input OTP
description: New Breadcrumb and Input OTP components.
date: 2024-03-08
---
We've added a new Breadcrumb component and an Input OTP component.
### Breadcrumb
An accessible and flexible breadcrumb component. It has support for collapsed items, custom separators, bring-your-own routing `<Link />` and composable with other shadcn/ui components.
<ComponentPreview styleName="new-york-v4" name="breadcrumb-demo" />
[See more examples](/docs/components/breadcrumb)
### Input OTP
A fully featured input OTP component. It has support for numeric and alphanumeric codes, custom length, copy-paste and accessible. Input OTP is built on top of [input-otp](https://github.com/guilhermerodz/input-otp) by [@guilherme_rodz](https://twitter.com/guilherme_rodz).
<ComponentPreview styleName="new-york-v4" name="input-otp-demo" />
[Read the docs](/docs/components/input-otp)
If you have a [v0](https://v0.dev) account, the new components are available for generation.

31
apps/v4/content/docs/changelog/2024-04-lift-mode.mdx Normal file
View File

@@ -0,0 +1,31 @@
---
title: April 2024 - Lift Mode
description: A new mode for Blocks to lift smaller components for copy and paste.
date: 2024-04-05
---
We're introducing a new mode for [Blocks](/blocks) called **Lift Mode**.
Enable Lift Mode to automatically "lift" smaller components from a block template for copy and paste.
<a href="/blocks">
<Image
src="/images/lift-mode-light.png"
width="1432"
height="1050"
alt="Lift Mode"
className="mt-6 w-full overflow-hidden rounded-2xl border dark:hidden"
/>
<Image
src="/images/lift-mode-dark.png"
width="1432"
height="1069"
alt="Lift Mode"
className="mt-6 hidden w-full overflow-hidden rounded-2xl border shadow-sm dark:block"
/>
<span className="sr-only">View the blocks library</span>
</a>
With Lift Mode, you'll be able to copy the smaller components that make up a block template, like cards, buttons, and forms, and paste them directly into your project.
Visit the [Blocks](/blocks) page to try it out.

45
apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx Normal file
View File

@@ -0,0 +1,45 @@
---
title: August 2024 - npx shadcn init
description: Complete CLI rewrite with support for all major React frameworks.
date: 2024-08-31
---
The new CLI is now available. It's a complete rewrite with a lot of new features and improvements. You can now install components, themes, hooks, utils and more using `npx shadcn add`.
This is a major step towards distributing code that you and your LLMs can access and use.
1. First up, the CLI now has support for all major React frameworks out of the box. Next.js, Remix, Vite and Laravel. And when you init into a new app, we update your existing Tailwind files instead of overriding.
2. A component now ships its own dependencies. Take the accordion for example, it can define its Tailwind keyframes. When you add it to your project, we'll update your tailwind.config.ts file accordingly.
3. You can also install remote components using url. `npx shadcn add https://acme.com/registry/navbar.json`.
4. We have also improved the init command. It does framework detection and can even init a brand new Next.js app in one command. `npx shadcn init`.
5. We have created a new schema that you can use to ship your own component registry. And since it has support for urls, you can even use it to distribute private components.
6. And a few more updates like better error handling and monorepo support.
You can try the new cli today.
```bash
npx shadcn init sidebar-01 login-01
```
### Update Your Project
To update an existing project to use the new CLI, update your `components.json` file to include import aliases for your **components**, **utils**, **ui**, **lib** and **hooks**.
```json showLineNumbers {7-13} title="components.json"
{
"$schema": "https://ui.shadcn.com/schema.json",
"style": "new-york",
"tailwind": {
// ...
},
"aliases": {
"components": "@/components",
"utils": "@/lib/utils",
"ui": "@/components/ui",
"lib": "@/lib",
"hooks": "@/hooks"
}
}
```
If you're using a different import alias prefix, e.g. `~`, replace `@` with your prefix.

11
apps/v4/content/docs/changelog/2024-10-react-19.mdx Normal file
View File

@@ -0,0 +1,11 @@
---
title: October 2024 - React 19
description: shadcn/ui is now compatible with React 19 and Next.js 15.
date: 2024-10-29
---
shadcn/ui is now compatible with React 19 and Next.js 15.
We published a guide to help you upgrade your project to React 19.
Read more [here](/docs/react-19).

13
apps/v4/content/docs/changelog/2024-10-sidebar.mdx Normal file
View File

@@ -0,0 +1,13 @@
---
title: October 2024 - Sidebar
description: 25 components to help you build all kinds of sidebars.
date: 2024-10-18
---
Introducing sidebar.tsx: 25 components to help you build all kinds of sidebars.
I don't like building sidebars. So I built 30+ of them. All types. Then simplified the core into sidebar.tsx: a strong foundation to build on top of.
It works with Next.js, Remix, Vite & Laravel.
See the announcement [here](https://x.com/shadcn/status/1847359896557408461).

13
apps/v4/content/docs/changelog/2024-11-icons.mdx Normal file
View File

@@ -0,0 +1,13 @@
---
title: November 2024 - Icons
description: The new-york style now uses Lucide as the default icon set.
date: 2024-11-06
---
An update on icons. The new-york style now uses Lucide as the default icon set.
- New projects will use Lucide by default
- No breaking changes for existing projects
- Use the CLI to (optionally) migrate primitives to Lucide
For more info on why we're doing this, see the [thread](https://x.com/shadcn/status/1853902179041702169).

18
apps/v4/content/docs/changelog/2024-12-monorepo.mdx Normal file
View File

@@ -0,0 +1,18 @@
---
title: December 2024 - Monorepo Support
description: New monorepo support in the CLI.
date: 2024-12-20
---
Until now, using shadcn/ui in a monorepo was a bit of a pain. You could add
components using the CLI, but you had to manage where the components
were installed and manually fix import paths.
With the new monorepo support in the CLI, we've made it a lot easier to use
shadcn/ui in a monorepo.
The CLI now understands the monorepo structure and will install the components,
dependencies and registry dependencies to the correct paths and handle imports
for you.
Read more in the [docs](/docs/monorepo).

11
apps/v4/content/docs/changelog/2025-01-blocks.mdx Normal file
View File

@@ -0,0 +1,11 @@
---
title: January 2025 - Blocks Community
description: Inviting the community to contribute to the blocks library.
date: 2025-01-14
---
We are inviting the community to contribute to the blocks library. Share your components and blocks with other developers and help build a library of high-quality, reusable components.
We'd love to see all types of blocks: applications, marketing, products, and more.
See the [docs](/docs/blocks) page to get started.

13
apps/v4/content/docs/changelog/2025-02-registry-schema.mdx Normal file
View File

@@ -0,0 +1,13 @@
---
title: February 2025 - Updated Registry Schema
description: Updated registry schema to support more features.
date: 2025-02-06
---
We're updating the registry schema to support more features.
Define code as a flat JSON file and distribute it via the CLI.
- Custom styles: bring your own design system, components & tokens
- Extend, override, mix & match components from third-party registries and LLMs
- Install themes, CSS vars, hooks, animations, and Tailwind layers & utilities

22
apps/v4/content/docs/changelog/2025-02-tailwind-v4.mdx Normal file
View File

@@ -0,0 +1,22 @@
---
title: February 2025 - Tailwind v4
description: First preview of Tailwind v4 and React 19 support.
date: 2025-02-19
---
We shipped the first preview of Tailwind v4 and React 19. Ready for you to try out. You can start using it today.
What's New:
- The CLI can now initialize projects with Tailwind v4.
- Full support for the new @theme directive and @theme inline option.
- All components are updated for Tailwind v4 and React 19.
- We've removed the forwardRefs and adjusted the types.
- Every primitive now has a data-slot attribute for styling.
- We've fixed and cleaned up the style of the components.
- We're deprecating the toast component in favor of sonner.
- Buttons now use the default cursor.
- We're deprecating the default style. New projects will use new-york.
- HSL colors are now converted to OKLCH.
Read more in the [docs](/docs/tailwind-v4).

9
apps/v4/content/docs/changelog/2025-04-cross-framework.mdx Normal file
View File

@@ -0,0 +1,9 @@
---
title: April 2025 - Cross-framework Route Support
description: The shadcn CLI can now auto-detect your framework and adapt routes for you.
date: 2025-04-09
---
The shadcn CLI can now auto-detect your framework and adapt routes for you.
Works with all frameworks including Laravel, Vite and React Router.

17
apps/v4/content/docs/changelog/2025-04-mcp.mdx Normal file
View File

@@ -0,0 +1,17 @@
---
title: April 2025 - MCP
description: Zero-config MCP support for shadcn/ui registry.
date: 2025-04-30
---
We're working on zero-config MCP support for shadcn/ui registry. One command `npx shadcn registry:mcp` to make any registry mcp-compatible.
<Image
src="/images/mcp.jpeg"
width="1432"
height="1050"
alt="MCP Server"
className="mt-6 w-full overflow-hidden rounded-2xl border"
/>
Learn more in the [thread here](https://x.com/shadcn/status/1917597228513853603).

11
apps/v4/content/docs/changelog/2025-04-shadcn-2-5.mdx Normal file
View File

@@ -0,0 +1,11 @@
---
title: April 2025 - shadcn 2.5.0
description: Resolve anywhere - registries can now place files anywhere in an app.
date: 2025-04-26
---
We tagged shadcn 2.5.0 earlier this week. It comes with a pretty cool feature: **resolve anywhere**.
Registries can now place files anywhere in an app and we'll properly resolve imports. No need to stick to a fixed file structure. It can even add files outside the registry itself.
On install, we track all files and perform a multi-pass resolution to correctly handle imports and aliases. It's fast.

11
apps/v4/content/docs/changelog/2025-05-new-site.mdx Normal file
View File

@@ -0,0 +1,11 @@
---
title: May 2025 - New Site
description: Upgraded ui.shadcn.com to Next.js 15.3 and Tailwind v4.
date: 2025-05-30
---
We've upgraded [ui.shadcn.com](https://ui.shadcn.com) to Next.js 15.3 and Tailwind v4. The site now uses the upgraded `new-york` components.
We've also made some minor design updates to make the site faster and easier to navigate.
This upgrade unlocks a lot of new features that we're working on. More to come.

13
apps/v4/content/docs/changelog/2025-06-calendar.mdx Normal file
View File

@@ -0,0 +1,13 @@
---
title: June 2025 - Calendar Component
description: Upgraded Calendar component with React DayPicker and 30+ calendar blocks.
date: 2025-06-06
---
We've upgraded the `Calendar` component to the latest version of [React DayPicker](https://daypicker.dev).
This is a major upgrade and includes a lot of new features and improvements.
<Image src="/images/calendar-2.png" alt="Calendar" width={676} height={895} />
To upgrade your project to the latest version of the `Calendar` component, see the [upgrade guide](/docs/components/calendar#upgrade-guide).

22
apps/v4/content/docs/changelog/2025-06-radix-ui.mdx Normal file
View File

@@ -0,0 +1,22 @@
---
title: June 2025 - radix-ui Migration
description: A new command to migrate to the new radix-ui package.
date: 2025-06-11
---
We've added a new command to migrate to the new `radix-ui` package. This command will replace all `@radix-ui/react-*` imports with `radix-ui`.
```bash
npx shadcn@latest migrate radix
```
It will automatically update all imports in your `ui` components and install `radix-ui` as a dependency.
```diff showLineNumbers title="components/ui/alert-dialog.tsx"
- import * as AlertDialogPrimitive from "@radix-ui/react-alert-dialog"
+ import { AlertDialog as AlertDialogPrimitive } from "radix-ui"
```
Make sure to test your components and project after running the command.
**Note:** To update imports for newly added components, run the migration command again.

22
apps/v4/content/docs/changelog/2025-07-local-file-support.mdx Normal file
View File

@@ -0,0 +1,22 @@
---
title: July 2025 - Local File Support
description: Initialize projects and add components from local JSON files.
date: 2025-07-07
---
The shadcn CLI now supports local files. Initialize projects and add components, themes, hooks, utils and more from local JSON files.
```bash
# Initialize a project from a local file
npx shadcn init ./template.json
# Add a component from a local file
npx shadcn add ./block.json
```
This feature enables powerful new workflows:
- **Zero setup** - No remote registries required
- **Faster development** - Test registry items locally before publishing
- **Enhanced workflow for agents and MCP** - Generate and run registry items locally
- **Private components** - Keep proprietary components local and private.

11
apps/v4/content/docs/changelog/2025-07-universal-registry.mdx Normal file
View File

@@ -0,0 +1,11 @@
---
title: July 2025 - Universal Registry Items
description: Create registry items that can be distributed to any project.
date: 2025-07-11
---
We've added support for universal registry items. This allows you to create registry items that can be distributed to any project i.e. no framework, no components.json, no tailwind, no react required.
This new registry item type unlocks a lot of new workflows. You can now distribute code, config, rules, docs, anything to any code project.
See the [docs](/docs/registry/examples) for more details and examples.

206
apps/v4/content/docs/changelog/2025-08-cli-3-mcp.mdx Normal file
View File

@@ -0,0 +1,206 @@
---
title: August 2025 - shadcn CLI 3.0 and MCP Server
description: Namespaced registries, advanced authentication, new commands and a completely rewritten registry engine.
date: 2025-08-27
---
We just shipped shadcn CLI 3.0 with support for namespaced registries, advanced authentication, new commands and a completely rewritten registry engine.
### What's New
- [Namespaced Registries](#namespaced-registries) - Install components using `@registry/name` format.
- [Private Registries](#private-registries) - Secure your registry with advanced authentication.
- [Search & Discovery](#search--discovery) - New commands to find and view code before installing.
- [MCP Server](#mcp-server) - MCP server for all registries.
- [Faster Everything](#faster-everything) - Completely rewritten registry resolution.
- [Improved Error Handling](#improved-error-handling) - Better error messages for users and LLMs.
- [Upgrade Guide](#upgrade-guide) - Migration notes for existing users.
### Namespaced Registries
The biggest change in 3.0 is namespaced registries. You can now install components from registries: a community registry, your company's private registry or internal registry, using the `@registry/name` format.
This makes it easier to distribute code across teams and projects.
Configure registries in your `components.json`:
```json title="components.json"
{
"registries": {
"@acme": "https://acme.com/r/{name}.json",
"@internal": {
"url": "https://registry.company.com/{name}",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
```
Then use the `@registry/name` format to install components:
```bash
npx shadcn add @acme/button @internal/auth-system
```
It's completely decentralized. There's no central registrar. Create any namespace you want and organize components however makes sense for your team.
```json title="components.json" showLineNumbers
{
"registries": {
"@design": "https://registry.company.com/create/{name}.json",
"@engineering": "https://registry.company.com/eng/{name}.json",
"@marketing": "https://registry.company.com/marketing/{name}.json"
}
}
```
Components can even depend on resources from different registries. Everything gets resolved and installed automatically from the right sources.
```json title="registry-item.json" showLineNumbers
{
"name": "dashboard",
"type": "registry:block",
"registryDependencies": [
"@shadcn/card", // From default registry
"@v0/chart", // From v0 registry
"@acme/data-table", // From acme registry
"@lib/data-fetcher", // Utility library
"@ai/analytics-prompt" // AI prompt resource
]
}
```
### Private Registries
Need to keep your components private? We've got you covered. Configure authentication with tokens, API keys, or custom headers:
```json title="components.json"
{
"registries": {
"@private": {
"url": "https://registry.company.com/{name}.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
```
Your private components stay private. Perfect for enterprise teams with proprietary UI libraries.
We support all major authentication methods: basic auth, bearer token, API key query params and custom headers.
See the [authentication docs](/docs/registry/authentication) for more details.
### Search & Discovery
Three new commands make it easy to find exactly what you need:
1. View items from the registry before installing
```bash
npx shadcn view @acme/auth-system
```
2. Search items from registries
```bash
npx shadcn search @tweakcn -q "dark"
```
3. List all items from a registry
```bash
npx shadcn list @acme
```
Preview components before installing them. Search across multiple registries. See the code and all dependencies upfront.
### MCP Server
<Image
src="/images/mcp.jpeg"
width="1432"
height="1050"
alt="MCP Server"
className="mt-6 w-full overflow-hidden rounded-2xl border"
/>
Back in April, we [introduced](https://x.com/shadcn/status/1917597228513853603) the first version of the MCP server. Since then, we've taken everything we learned and built a better MCP server.
Here's what's new:
- Works with all registries. Zero config
- One command to add to your favorite MCP clients
- We improved the underlying tools
- Better integration with the CLI and registries
- Support for multiple registries in the same project
Add the MCP server to your project:
```bash
npx shadcn@latest mcp init
```
See the [docs](/docs/mcp) for more details.
### Faster Everything
We completely rewrote the registry resolution engine from scratch. It's faster, smarter, and handles even the trickiest dependency trees.
- Up to 3x faster dependency resolution
- Smarter file deduplication and merging
- Better monorepo support out of the box
- Updated `build` command for registry authors
### Improved Error Handling
Registry developers can now provide custom error messages to help guide users (and LLMs) when things go wrong. The CLI displays helpful, actionable errors for common issues:
```txt
Unknown registry "@acme". Make sure it is defined in components.json as follows:
{
"registries": {
"@acme": "[URL_TO_REGISTRY]"
}
}
```
Missing environment variables? The CLI tells you exactly what's needed:
```txt
Registry "@private" requires the following environment variables:
• REGISTRY_TOKEN
Set the required environment variables in your .env or .env.local file.
```
Registry authors can provide custom error messages in their responses to help users and AI agents understand and fix issues quickly.
```txt
Error:
You are not authorized to access the item at http://example.com/r/component.
Message:
[Unauthorized] Your API key has expired. Renew it at https://example.com/api/renew-key.
```
### Upgrade Guide
Here's the best part: there are no breaking changes for users. Your existing `components.json` works exactly the same. All your installed components work exactly the same.
For developers, if you're using the programmatic APIs directly, we've deprecated a few functions in favor of better ones:
- `fetchRegistry` → `getRegistry`
- `resolveRegistryTree` → `resolveRegistryItems`
- Schema moved from `shadcn/registry` to `shadcn/schema` package
```diff
- import { registryItemSchema } from "shadcn/registry"
+ import { registryItemSchema } from "shadcn/schema"
```
That's it. Seriously. Everything else just works.

19
apps/v4/content/docs/changelog/2025-09-registry-index.mdx Normal file
View File

@@ -0,0 +1,19 @@
---
title: September 2025 - Registry Index
description: An index of open source registries that you can install items from.
date: 2025-09-02
---
We've created an index of open source registries that you can install items from.
You can search, view and add items from the registry index without configuring the `components.json` file.
They'll be automatically added to your `components.json` file for you.
```bash
npx shadcn add @ai-elements/prompt-input
```
The full list of registries is available at [https://ui.shadcn.com/r/registries.json](https://ui.shadcn.com/r/registries.json).
To add a registry to the index, submit a PR to the `shadcn/ui` repository. See the [registry index documentation](/docs/registry/registry-index) for more details.

418
apps/v4/content/docs/changelog/2025-10-new-components.mdx Normal file
View File

@@ -0,0 +1,418 @@
---
title: October 2025 - New Components
description: Spinner, Kbd, Button Group, Input Group, Field, Item, and Empty components.
date: 2025-10-03
---
For this round of components, I looked at what we build every day, the boring stuff we rebuild over and over, and made reusable abstractions you can actually use.
**These components work with every component library, Radix, Base UI, React Aria, you name it. Copy and paste to your projects.**
- [Spinner](#spinner): An indicator to show a loading state.
- [Kbd](#kbd): Display a keyboard key or group of keys.
- [Button Group](#button-group): A group of buttons for actions and split buttons.
- [Input Group](#input-group): Input with icons, buttons, labels and more.
- [Field](#field): One component. All your forms.
- [Item](#item): Display lists of items, cards, and more.
- [Empty](#empty): Use this one for empty states.
### Spinner
Okay let's start with the easiest ones: **Spinner** and **Kbd**. Pretty basic. We all know what they do.
Here's how you render a spinner:
```tsx
import { Spinner } from "@/components/ui/spinner"
```
```tsx
<Spinner />
```
Here's what it looks like:
<ComponentPreview styleName="new-york-v4"
name="spinner-basic"
/>
Here's what it looks like in a button:
<ComponentPreview styleName="new-york-v4"
name="spinner-button"
/>
You can edit the code and replace it with your own spinner.
<ComponentPreview styleName="new-york-v4"
name="spinner-custom"
/>
### Kbd
Kbd is a component that renders a keyboard key.
```tsx
import { Kbd, KbdGroup } from "@/components/ui/kbd"
```
```tsx
<Kbd>Ctrl</Kbd>
```
Use `KbdGroup` to group keyboard keys together.
```tsx showLineNumbers
<KbdGroup>
<Kbd>Ctrl</Kbd>
<Kbd>B</Kbd>
</KbdGroup>
```
<ComponentPreview styleName="new-york-v4"
name="kbd-demo"
/>
You can add it to buttons, tooltips, input groups, and more.
### Button Group
I got a lot of requests for this one: Button Group. It's a container that groups related buttons together with consistent styling. Great for action groups, split buttons, and more.
<ComponentPreview styleName="new-york-v4"
name="button-group-demo"
/>
Here's the code:
```tsx
import { ButtonGroup } from "@/components/ui/button-group"
```
```tsx showLineNumbers
<ButtonGroup>
<Button>Button 1</Button>
<Button>Button 2</Button>
</ButtonGroup>
```
You can nest button groups to create more complex layouts with spacing.
```tsx showLineNumbers
<ButtonGroup>
<ButtonGroup>
<Button>Button 1</Button>
<Button>Button 2</Button>
</ButtonGroup>
<ButtonGroup>
<Button>Button 3</Button>
<Button>Button 4</Button>
</ButtonGroup>
</ButtonGroup>
```
Use `ButtonGroupSeparator` to create split buttons. Classic dropdown pattern.
<ComponentPreview styleName="new-york-v4"
name="button-group-dropdown"
/>
You can also use it to add prefix or suffix buttons and text to inputs.
<ComponentPreview styleName="new-york-v4"
name="button-group-select"
/>
```tsx showLineNumbers
<ButtonGroup>
<ButtonGroupText>Prefix</ButtonGroupText>
<Input placeholder="Type something here..." />
<Button>Button</Button>
</ButtonGroup>
```
### Input Group
Input Group lets you add icons, buttons, and more to your inputs. You know, all those little bits you always need around your inputs.
```tsx
import {
InputGroup,
InputGroupAddon,
InputGroupInput,
} from "@/components/ui/input-group"
```
```tsx showLineNumbers
<InputGroup>
<InputGroupInput placeholder="Search..." />
<InputGroupAddon>
<SearchIcon />
</InputGroupAddon>
</InputGroup>
```
Here's a preview with icons:
<ComponentPreview
styleName="new-york-v4"
name="input-group-icon"
className="[&_.preview]:h-[300px] [&_pre]:h-[300px]!"
/>
You can also add buttons to the input group.
<ComponentPreview
styleName="new-york-v4"
name="input-group-button"
className="[&_.preview]:h-[300px] [&_pre]:h-[300px]!"
/>
Or text, labels, tooltips, ...
<ComponentPreview
styleName="new-york-v4"
name="input-group-text"
className="[&_.preview]:h-[350px] [&_pre]:h-[350px]!"
/>
It also works with textareas so you can build really complex components with lots of knobs and dials or yet another prompt form.
<ComponentPreview
styleName="new-york-v4"
name="input-group-textarea"
className="[&_.preview]:h-[450px] [&_pre]:h-[450px]!"
/>
Oh here are some cool ones with spinners:
<ComponentPreview
styleName="new-york-v4"
name="input-group-spinner"
className="[&_.preview]:h-[350px] [&_pre]:h-[350px]!"
/>
### Field
Introducing **Field**, a component for building really complex forms. The abstraction here is beautiful.
It took me a long time to get it right but I made it work with all your form libraries: Server Actions, React Hook Form, TanStack Form, Bring Your Own Form.
```tsx
import {
Field,
FieldDescription,
FieldError,
FieldLabel,
} from "@/components/ui/field"
```
Here's a basic field with an input:
```tsx showLineNumbers
<Field>
<FieldLabel htmlFor="username">Username</FieldLabel>
<Input id="username" placeholder="Max Leiter" />
<FieldDescription>
Choose a unique username for your account.
</FieldDescription>
</Field>
```
<ComponentPreview
styleName="new-york-v4"
name="field-input"
className="[&_.preview]:h-[350px] [&_pre]:h-[350px]!"
/>
It works with all form controls. Inputs, textareas, selects, checkboxes, radios, switches, sliders, you name it. Here's a full example:
<ComponentPreview
styleName="new-york-v4"
name="field-demo"
className="[&_.preview]:h-[850px] [&_pre]:h-[850px]!"
/>
Here are some checkbox fields:
<ComponentPreview
styleName="new-york-v4"
name="field-checkbox"
className="[&_.preview]:h-[500px] [&_pre]:h-[500px]!"
/>
You can group fields together using `FieldGroup` and `FieldSet`. Perfect for
multi-section forms.
```tsx showLineNumbers
<FieldSet>
<FieldLegend />
<FieldGroup>
<Field />
<Field />
</FieldGroup>
</FieldSet>
```
<ComponentPreview
styleName="new-york-v4"
name="field-fieldset"
className="[&_.preview]:h-[500px] [&_pre]:h-[500px]!"
/>
Making it responsive is easy. Use `orientation="responsive"` and it switches
between vertical and horizontal layouts based on container width. Done.
<ComponentPreview
styleName="new-york-v4"
name="field-responsive"
className="[&_.preview]:h-[600px] [&_pre]:h-[600px]!"
/>
Wait, here's more. Wrap your fields in `FieldLabel` to create a selectable field group. Really easy. And it looks great.
<ComponentPreview
styleName="new-york-v4"
name="field-choice-card"
className="[&_.preview]:h-[600px] [&_pre]:h-[600px]!"
/>
### Item
This one is a straightforward flex container that can house nearly any type of content.
I've built this so many times that I decided to create a component for it. Now I use it all the time. I use it to display lists of items, cards, and more.
```tsx
import {
Item,
ItemContent,
ItemDescription,
ItemMedia,
ItemTitle,
} from "@/components/ui/item"
```
Here's a basic item:
```tsx showLineNumbers
<Item>
<ItemMedia variant="icon">
<HomeIcon />
</ItemMedia>
<ItemContent>
<ItemTitle>Dashboard</ItemTitle>
<ItemDescription>Overview of your account and activity.</ItemDescription>
</ItemContent>
</Item>
```
<ComponentPreview
styleName="new-york-v4"
name="item-demo"
className="[&_.preview]:h-[300px] [&_.preview]:p-4 [&_pre]:h-[300px]!"
/>
You can add icons, avatars, or images to the item.
<ComponentPreview
styleName="new-york-v4"
name="item-icon"
className="[&_.preview]:h-[300px] [&_.preview]:p-4 [&_pre]:h-[300px]!"
/>
<ComponentPreview
styleName="new-york-v4"
name="item-avatar"
className="[&_.preview]:h-[300px] [&_.preview]:p-4 [&_pre]:h-[300px]!"
/>
And here's what a list of items looks like with `ItemGroup`:
<ComponentPreview
styleName="new-york-v4"
name="item-group"
className="[&_.preview]:h-[500px] [&_.preview]:p-4 [&_pre]:h-[500px]!"
/>
Need it as a link? Use the `asChild` prop:
```tsx showLineNumbers
<Item asChild>
<a href="/dashboard">
<ItemMedia variant="icon">
<HomeIcon />
</ItemMedia>
<ItemContent>
<ItemTitle>Dashboard</ItemTitle>
<ItemDescription>Overview of your account and activity.</ItemDescription>
</ItemContent>
</a>
</Item>
```
<ComponentPreview
styleName="new-york-v4"
name="item-link"
className="[&_.preview]:h-[400px] [&_.preview]:p-4 [&_pre]:h-[400px]!"
/>
### Empty
Okay last one: **Empty**. Use this to display empty states in your app.
```tsx
import {
Empty,
EmptyContent,
EmptyDescription,
EmptyMedia,
EmptyTitle,
} from "@/components/ui/empty"
```
Here's how you use it:
```tsx showLineNumbers
<Empty>
<EmptyMedia variant="icon">
<InboxIcon />
</EmptyMedia>
<EmptyTitle>No messages</EmptyTitle>
<EmptyDescription>You don't have any messages yet.</EmptyDescription>
<EmptyContent>
<Button>Send a message</Button>
</EmptyContent>
</Empty>
```
<ComponentPreview
styleName="new-york-v4"
name="empty-demo"
className="[&_.preview]:h-[400px] [&_.preview]:p-4 [&_pre]:h-[400px]!"
/>
You can use it with avatars:
<ComponentPreview
styleName="new-york-v4"
name="empty-avatar"
className="[&_.preview]:h-[400px] [&_pre]:h-[400px]!"
/>
Or with input groups for things like search results or email subscriptions:
<ComponentPreview
styleName="new-york-v4"
name="empty-input-group"
className="[&_.preview]:h-[450px] [&_pre]:h-[450px]!"
/>
That's it. Seven new components. Works with all your libraries. Ready for your projects.

11
apps/v4/content/docs/changelog/2025-10-registry-directory.mdx Normal file
View File

@@ -0,0 +1,11 @@
---
title: October 2025 - Registry Directory
description: A list of code registries you can browse and pull code and components from.
date: 2025-10-28
---
We just published the Registry Directory: a list of code registries you can browse and pull code and components from.
https://ui.shadcn.com/docs/directory
Built into the CLI. No config required.

46
apps/v4/content/docs/changelog/2025-12-shadcn-create.mdx Normal file
View File

@@ -0,0 +1,46 @@
---
title: December 2025 - npx shadcn create
description: Customize everything. Pick your component library, icons, base color, theme, fonts and create your own version of shadcn/ui.
date: 2025-12-12
---
From the very first commit, the goal of shadcn/ui was to make it customizable.
The idea is to give you solid defaults, spacing, color tokens, animations, accessibility, and then let you take it from there. Tweak the code. Add new components. Change the colors. Build your own version.
But somewhere along the way, all apps started looking the same. I guess the defaults were a little _too_ good. My bad.
Today, we're changing that: **npx shadcn create**.
Customize Everything. Pick your component library, icons, base color, theme, fonts and create your own version of shadcn/ui.
We're starting with **5 new visual styles**, designed to help your UI actually feel like _your_ UI.
- **Vega** – The classic shadcn/ui look.
- **Nova** – Reduced padding and margins for compact layouts.
- **Maia** – Soft and rounded, with generous spacing.
- **Lyra** – Boxy and sharp. Pairs well with mono fonts.
- **Mira** – Compact. Made for dense interfaces.
**This goes beyond theming**.
Your config doesn't just change colors, it rewrites the component code to match your setup. Fonts, spacing, structure, even the libraries you use, everything adapts to your preferences.
The new CLI takes care of it all.
Start with a component library. Choose between Radix or Base UI.
We rebuilt every component for Base UI, keeping the same abstraction.
They are fully compatible with your existing components, even those pulled from remote registries.
When you pull down components, we auto-detect your library and apply the right transformations.
**It's time to build something that doesn't look like everything else.**
Now available for Next.js, Vite, TanStack Start and v0.
<Button asChild>
<Link href="/create" className="mt-6 no-underline!">
Get Started
</Link>
</Button>

45
apps/v4/content/docs/changelog/2026-01-base-ui.mdx Normal file
View File

@@ -0,0 +1,45 @@
---
title: January 2026 - Base UI Documentation
description: Full documentation for Base UI components.
date: 2026-01-20
---
We've shipped full documentation for Base UI components.
<div className="mt-6 flex w-full items-center justify-center rounded-lg border bg-muted/50 py-32">
<svg width="17" height="24" viewBox="0 0 17 24" className="size-12">
<path
fill="currentColor"
d="M9.5001 7.01537C9.2245 6.99837 9 7.22385 9 7.49999V23C13.4183 23 17 19.4183 17 15C17 10.7497 13.6854 7.27351 9.5001 7.01537Z"
/>
<path
fill="currentColor"
d="M8 9.8V12V23C3.58172 23 0 19.0601 0 14.2V12V1C4.41828 1 8 4.93989 8 9.8Z"
/>
</svg>
</div>
When we launched `npx shadcn create` in December, we introduced the ability to choose between Radix and Base UI as your component library. Today, we're following up with complete documentation for all Base UI components.
### What's New
- **Full Base UI docs** - Every component now has dedicated documentation for Base UI, covering usage, props, and examples.
- **Rebuilt examples** - All component examples have been rebuilt for both Radix and Base UI. Switch between them to see the implementation differences.
- **Side-by-side comparison** - The docs make it easy to compare how components work across both libraries.
### Same Abstraction, Different Primitives
The goal remains the same: give you a consistent API regardless of which primitive library you choose. The components look and behave the same way. Only the underlying implementation changes.
```tsx
// Works the same whether you're using Radix or Base UI.
import { Dialog, DialogContent, DialogTrigger } from "@/components/ui/dialog"
```
If you're starting a new project, run `npx shadcn create` and pick your preferred library. The CLI handles the rest.
<Button asChild size="sm">
<Link href="/create" className="mt-6 no-underline!">
Try shadcn/create
</Link>
</Button>

69
apps/v4/content/docs/changelog/2026-01-inline-side-styles.mdx Normal file
View File

@@ -0,0 +1,69 @@
---
title: January 2026 - Inline Start and End Styles
description: We've updated the styles for Base UI components to support inline-start and inline-end side values.
date: 2026-01-23
---
We've updated the styles for Base UI components to support `inline-start` and `inline-end` side values. The following components now support these values:
- Tooltip
- Popover
- Combobox
- Context Menu
- Dropdown Menu
- Hover Card
- Menubar
- Select
### What Changed
We added new Tailwind classes to handle the logical side values:
```diff
<PopoverPrimitive.Popup
className={cn(
"... data-[side=bottom]:slide-in-from-top-2
data-[side=left]:slide-in-from-right-2
data-[side=right]:slide-in-from-left-2
data-[side=top]:slide-in-from-bottom-2
+ data-[side=inline-start]:slide-in-from-right-2
+ data-[side=inline-end]:slide-in-from-left-2 ...",
className
)}
/>
```
### Usage
```tsx
<Popover>
<PopoverTrigger>Open</PopoverTrigger>
<PopoverContent side="inline-start">
{/* Opens on the left in LTR, right in RTL */}
</PopoverContent>
</Popover>
```
### LLM Prompt
Ask your LLM to update your components by running the following prompt:
```txt showLineNumbers
Add inline-start and inline-end support to my shadcn/ui components. Add the following Tailwind classes to each component:
| File | Component | Add Classes |
|------|-----------|-------------|
| tooltip.tsx | TooltipContent | `data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2` |
| tooltip.tsx | TooltipArrow | `data-[side=inline-start]:top-1/2! data-[side=inline-start]:-right-1 data-[side=inline-start]:-translate-y-1/2
data-[side=inline-end]:top-1/2! data-[side=inline-end]:-left-1 data-[side=inline-end]:-translate-y-1/2` |
| popover.tsx | PopoverContent | `data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2` |
| hover-card.tsx | HoverCardContent | `data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2` |
| select.tsx | SelectContent | `data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2
data-[align-trigger=true]:animate-none` and add `data-align-trigger={alignItemWithTrigger}` attribute |
| combobox.tsx | ComboboxContent | `data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2` |
| dropdown-menu.tsx | DropdownMenuContent | `data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2` |
| context-menu.tsx | ContextMenuContent | `data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2` |
| menubar.tsx | MenubarContent | `data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2` |
Add these classes next to the existing `data-[side=top]`, `data-[side=bottom]`, `data-[side=left]`, `data-[side=right]` classes.
```

82
apps/v4/content/docs/changelog/2026-01-rtl.mdx Normal file
View File

@@ -0,0 +1,82 @@
---
title: January 2026 - RTL Support
description: The shadcn CLI now supports RTL (right-to-left) layouts by automatically converting physical CSS classes to logical equivalents.
date: 2026-01-28
---
shadcn/ui now has first-class support for right-to-left (RTL) layouts. Your components automatically adapt for languages like Arabic, Hebrew, and Persian.
**This works with the [shadcn/ui components](/docs/components) as well as any component distributed on the shadcn registry.**
<ComponentPreview
styleName="base-nova"
name="alert-rtl"
direction="rtl"
previewClassName="h-auto sm:h-72 p-6"
/>
### Our approach to RTL
Traditionally, component libraries that support RTL ship with logical classes baked in. This means everyone has to work with classes like `ms-4` and `start-2`, even if they're only building for LTR layouts.
We took a different approach. The shadcn CLI transforms classes at install time, so you only see logical classes when you actually need them. If you're not building for RTL, you work with familiar classes like `ml-4` and `left-2`. When you enable RTL, the CLI handles the conversion for you.
**You don't have to learn RTL until you need it.**
### How it works
When you add components with `rtl: true` set in your `components.json`, the CLI automatically converts physical CSS classes like `ml-4` and `text-left` to their logical equivalents like `ms-4` and `text-start`.
- Physical positioning classes like `left-*` and `right-*` become `start-*` and `end-*`.
- Margin and padding classes like `ml-*` and `pr-*` become `ms-*` and `pe-*`.
- Text alignment classes like `text-left` become `text-start`.
- Directional props are updated to use logical values.
- Supported icons are automatically flipped using `rtl:rotate-180`.
- Animations like `slide-in-from-left` become `slide-in-from-start`.
### RTL examples for every component
We've added RTL examples for every component. You'll find live previews and code on each [component page](/docs/components).
<ComponentPreview
styleName="base-nova"
name="card-rtl"
direction="rtl"
previewClassName="h-auto"
/>
### CLI updates
**New projects**: Use the `--rtl` flag with `init` or `create` to enable RTL from the start.
```bash
npx shadcn@latest init --rtl
```
```bash
npx shadcn@latest create --rtl
```
**Existing projects**: Migrate your components with the `migrate rtl` command.
```bash
npx shadcn@latest migrate rtl
```
This transforms all components in your `ui` directory to use logical classes. You can also pass a specific path or glob pattern.
## Try it out
Click the link below to open a Next.js project with RTL support in v0.
[![Open in v0](https://v0.app/chat-static/button.svg)](https://v0.app/chat/api/open?url=https://github.com/shadcn-ui/next-template-rtl)
### Links
- [RTL Documentation](/docs/rtl)
- [Font Recommendations](/docs/rtl#font-recommendations)
- [Animations](/docs/rtl#animations)
- [Migrating Existing Components](/docs/rtl#migrating-existing-components)
- [Next.js Setup](/docs/rtl/next)
- [Vite Setup](/docs/rtl/vite)
- [TanStack Start Setup](/docs/rtl/start)

18
apps/v4/content/docs/changelog/2026-02-blocks.mdx Normal file
View File

@@ -0,0 +1,18 @@
---
title: February 2026 - Blocks for Radix and Base UI
description: All blocks are now available for both Radix and Base UI.
date: 2026-02-06
---
All [blocks](/blocks) are now available for both Radix and Base UI.
- **All blocks for both libraries** - Every block, including login, signup, sidebar and dashboard blocks, is now available in both Radix and Base UI variants.
- **Same CLI workflow** - Run `npx shadcn add` and the CLI will pull the correct block variant based on your project configuration.
If you've already set up your project with `npx shadcn create`, blocks will automatically use your chosen library. No additional configuration needed.
```bash
npx shadcn@latest add login-01
```
Browse the full collection on the [blocks](/blocks) page.

38
apps/v4/content/docs/changelog/2026-02-radix-ui.mdx Normal file
View File

@@ -0,0 +1,38 @@
---
title: February 2026 - Unified Radix UI Package
description: The new-york style now uses the unified radix-ui package.
date: 2026-02-02
---
The `new-york` style now uses the unified `radix-ui` package instead of individual `@radix-ui/react-*` packages.
### What's Changed
When you add components using the `new-york` style, they will now import from `radix-ui` instead of separate packages:
```diff title="components/ui/dialog.tsx"
- import * as DialogPrimitive from "@radix-ui/react-dialog"
+ import { Dialog as DialogPrimitive } from "radix-ui"
```
This results in a cleaner `package.json` with a single `radix-ui` dependency instead of multiple `@radix-ui/react-*` packages.
### Migrating Existing Projects
If you have an existing project using the `new-york` style, you can migrate to the new `radix-ui` package using the migrate command:
```bash
npx shadcn@latest migrate radix
```
This will update all imports in your UI components and add `radix-ui` to your dependencies.
To migrate components outside of your `ui` directory, use the `path` argument:
```bash
npx shadcn@latest migrate radix src/components/custom
```
Once complete, you can remove any unused `@radix-ui/react-*` packages from your `package.json`.
See the [migrate radix documentation](/docs/cli#migrate-radix) for more details.

153
apps/v4/content/docs/changelog/2026-03-cli-v4.mdx Normal file
View File

@@ -0,0 +1,153 @@
---
title: March 2026 - shadcn/cli v4
description: More capable, easier to use. Built for you and your coding agents. Skills, presets, dry run, new templates, monorepo and more.
date: 2026-03-06
---
We're releasing version 4 of shadcn/cli. More capable, easier to use. Built for you and your coding agents. Here's everything new.
## shadcn/skills
shadcn/skills gives coding agents the context they need to work with your components and registry correctly. It covers both Radix and Base UI primitives, updated APIs, component patterns and registry workflows. The skill also knows how to use the shadcn CLI, when to invoke it and which flags to pass. Agents make fewer mistakes and produce code that actually matches your design system.
You can ask your agent things like:
- "create a new vite monorepo"
- "find me a hero from tailark, add it to the homepage, animate the text using an animation from react-bits"
- "install and configure a sign in page from @clerk"
```bash
npx skills add shadcn/ui
```
## Introducing --preset
A preset packs your entire design system config into a short code. Colors, theme, icon library, fonts, radius. One string, everything included.
Build your preset on [shadcn/create](/create), preview it live and grab the code when you're ready.
```bash
npx shadcn@latest init --preset a1Dg5eFl
```
Use it to scaffold projects from custom config, share with your team or publish in your registry. Drop it in prompts so your agent knows where to start. Use it across Claude, Codex, v0, Replit. Take your preset with you.
## Switching presets
When you're working on a new app, it can take a few tries to find something you like so we've made switching presets really easy. Run `init --preset` in your app, and the CLI will take care of reconfiguring everything, including your components.
```bash
npx shadcn@latest init --preset ad3qkJ7
```
## Skills + Presets
Your agent knows how to use presets. Scaffold a project, switch design systems, try something new.
- "create a new next app using --preset adtk27v"
- "let's try --preset adtk27v"
## New shadcn/create
To help you build custom presets, we rebuilt [shadcn/create](/create). It now includes a library of UI components you can use to preview your presets. See how your colors, fonts and radius apply to real components before you start building.
## New --dry-run, --diff, and --view flags
Inspect what a registry will add to your project before anything gets written. Review the payload yourself or pipe it to your coding agent for a second look.
```bash
npx shadcn@latest add button --dry-run
npx shadcn@latest add button --diff
npx shadcn@latest add button --view
```
## Updating primitives
You can use the `--diff` flag to check for registry updates. Or ask your agent: "check for updates from @shadcn and merge with my local changes".
```bash
npx shadcn@latest add button --diff
```
## shadcn init --template
`shadcn init` now scaffolds full project templates for Next.js, Vite, Laravel, React Router, Astro and TanStack Start. Dark mode included for Next.js and Vite.
```bash
npx shadcn@latest init
Select a template › - Use arrow-keys. Return to submit.
❯ Next.js
Vite
TanStack Start
React Router
Astro
Laravel
```
Use `--monorepo` to set up a monorepo.
```bash
npx shadcn@latest init -t next --monorepo
```
## shadcn init --base
Pick your primitives. Use `--base` to start a project with Radix or Base UI.
```bash
npx shadcn@latest init --base radix
```
## shadcn info
The `info` command now shows the full picture: framework, version, CSS vars, which components are installed, and where to find docs and examples for every component. Great for giving coding agents the context they need to work with your project.
```bash
npx shadcn@latest info
```
## shadcn docs
Get docs, code and examples for any UI component right from the CLI. Gives your coding agent the context to use your primitives correctly.
```bash
npx shadcn@latest docs combobox
combobox
- docs https://ui.shadcn.com/docs/components/radix/combobox
- examples https://ui.shadcn.com/code/apps/v4/registry/bases/radix/examples/combobox-example.tsx
- api https://base-ui.com/react/components/combobox
```
## registry:base and registry:font
Registries can now distribute an entire design system as a single payload using `registry:base`. Components, dependencies, CSS vars, fonts, config. One install, everything set up.
Fonts are now a first-class registry type. Install and configure them the same way you install components.
```json title="font-inter.json" showLineNumbers
{
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
"name": "font-inter",
"type": "registry:font",
"font": {
"family": "'Inter Variable', sans-serif",
"provider": "google",
"import": "Inter",
"variable": "--font-sans",
"subsets": ["latin"]
}
}
```
```bash
npx shadcn@latest add font-inter
```
## Links
- [shadcn/skills](/skills)
- [shadcn/create](/create)
- [shadcn/cli](/cli)
- [shadcn/registry](/docs/registry)

37
apps/v4/content/docs/changelog/2026-03-luma.mdx Normal file
View File

@@ -0,0 +1,37 @@
---
title: March 2026 - Introducing Luma
description: Rounded geometry. Soft elevation. Breathable layouts. Inspired by macOS Tahoe, minus the glass.
date: 2026-03-31
---
Introducing Luma, a new shadcn/ui style. Rounded geometry. Soft elevation. Breathable layouts. Inspired by macOS Tahoe, minus the glass.
<a href="/create">
<Image
src="/images/luma-light.png"
width="2160"
height="1832"
alt="Luma style preview"
className="mt-6 w-full overflow-hidden rounded-2xl border dark:hidden"
/>
<Image
src="/images/luma-dark.png"
width="2160"
height="1832"
alt="Luma style preview"
className="mt-6 hidden w-full overflow-hidden rounded-2xl border shadow-sm dark:block"
/>
<span className="sr-only">Try Luma in shadcn/create</span>
</a>
Luma is a new foundation for your next app. It gives components softer surfaces, more open spacing, and a calmer visual rhythm while keeping the same shadcn/ui workflow.
Like the other new styles, Luma goes beyond theming. It changes the geometry, spacing, and feel of the components so your app starts from a different visual baseline.
Available now in [shadcn/create](/create) for both Radix and Base UI.
<Button asChild size="sm">
<Link href="/create?preset=b2D0wqNxT" className="mt-6 no-underline!">
Try Luma
</Link>
</Button>

31
apps/v4/content/docs/changelog/2026-04-component-composition.mdx Normal file
View File

@@ -0,0 +1,31 @@
---
title: April 2026 - Component Composition
description: Composition sections across component pages—structured trees that help you and your agents build correct UI.
date: 2026-04-06
---
We've added **Composition** sections across the component docs so you can see the correct structure at a glance: what wraps what, which subcomponents belong together, and how to avoid invalid nesting.
```text
Card
├── CardHeader
│ ├── CardTitle
│ ├── CardDescription
│ └── CardAction
├── CardContent
└── CardFooter
```
## Why we added this
We've found that **LLMs and coding agents compose elements more reliably** when they can see the full structure: fewer missing wrappers, fewer wrong hierarchies, better matches to the examples.
### Bring docs into your agent
You or your LLM can pull the same component documentation, including composition, usage, and examples, into context from the CLI:
```bash
npx shadcn@latest docs card
```
If you're using the [shadcn/skills](/docs/skills), this is done automatically for you.

35
apps/v4/content/docs/changelog/2026-04-partial-preset-apply.mdx Normal file
View File

@@ -0,0 +1,35 @@
---
title: April 2026 - Partial Preset Apply
description: Apply only the theme or fonts from a preset while keeping your existing components.
date: 2026-04-22
---
You can now selectively apply a preset.
Say someone shares a preset with you and you already have your own components, but you like the theme or the fonts. Now you can apply just that.
Keep your components. Apply only what you want.
```bash
# Apply the full preset.
npx shadcn@latest apply --preset b2D0vQ7G4
# Apply only the theme.
npx shadcn@latest apply --preset b2D0vQ7G4 --only theme
# Apply only the fonts.
npx shadcn@latest apply --preset b2D0vQ7G4 --only font
# Apply theme and fonts.
npx shadcn@latest apply --preset b2D0vQ7G4 --only theme,font
```
The default behavior is unchanged. Running `shadcn apply --preset <preset>` still applies the full preset.
Partial preset apply currently supports `theme` and `font`.
<Button asChild size="sm">
<Link href="/create" className="mt-6 no-underline!">
Try a Preset
</Link>
</Button>

24
apps/v4/content/docs/changelog/2026-04-pointer-cursor.mdx Normal file
View File

@@ -0,0 +1,24 @@
---
title: April 2026 - Pointer Cursor
description: Add cursor pointer behavior for buttons during project setup.
date: 2026-04-25
---
You can now enable `cursor: pointer` for buttons when initializing a project.
```bash
npx shadcn@latest init --pointer
```
This adds the following CSS to your global CSS file:
```css title="globals.css"
@layer base {
button:not(:disabled),
[role="button"]:not(:disabled) {
cursor: pointer;
}
}
```
The `--pointer` option is not part of preset codes. It is applied as a project setup option, similar to `--rtl`.

93
apps/v4/content/docs/changelog/2026-04-preset-commands.mdx Normal file
View File

@@ -0,0 +1,93 @@
---
title: April 2026 - shadcn preset
description: Decode, share, open, and resolve preset codes from the shadcn CLI.
date: 2026-04-28
---
We added `shadcn preset` commands for working with preset codes.
## Decode a preset
You can decode a preset code to see exactly what it contains:
```bash
npx shadcn@latest preset decode b5owWMfJ8l
```
```txt
Preset
code b5owWMfJ8l
version b
style mira
baseColor mauve
theme mauve
chartColor amber
iconLibrary hugeicons
font inter
fontHeading oxanium
radius large
menuAccent subtle
menuColor inverted-translucent
url https://ui.shadcn.com/create?preset=b5owWMfJ8l
```
## Resolve from a project
Use `preset resolve` in an existing project to see the preset that matches your current configuration.
```bash
npx shadcn@latest preset resolve
```
```txt
Preset
code b5Kc6P0Vc
version b
style luma
baseColor olive
theme lime
chartColor sky
iconLibrary hugeicons
font geist
fontHeading inherit
radius default
menuAccent subtle
menuColor default
url https://ui.shadcn.com/create?preset=b5Kc6P0Vc
```
It works with monorepos too:
```bash
npx shadcn@latest preset resolve -c apps/web
```
## Share or open
Use `preset url` when you need a shareable link:
```bash
npx shadcn@latest preset url b5owWMfJ8l
```
```txt
https://ui.shadcn.com/create?preset=b5owWMfJ8l
```
Use `preset open` to open the preset on shadcn/create for customization:
```bash
npx shadcn@latest preset open b5owWMfJ8l
```
```txt
Opening https://ui.shadcn.com/create?preset=b5owWMfJ8l in your browser.
```
This makes presets easier to inspect, share, and hand off to coding agents without manually decoding codes or building URLs.
<Button asChild size="sm">
<Link href="/create" className="mt-6 no-underline!">
Try a Preset
</Link>
</Button>

37
apps/v4/content/docs/changelog/2026-04-sera.mdx Normal file
View File

@@ -0,0 +1,37 @@
---
title: April 2026 - Introducing Sera
description: Minimal. Editorial. Typographic. Underline Controls and Uppercase Headings. Shaped by Print Design Principles.
date: 2026-04-16
---
Introducing Sera, a new shadcn/ui style. Minimal. Editorial. Typographic. Underline Controls and Uppercase Headings. Shaped by Print Design Principles.
<a href="/create?preset=b4xFeBLg4O">
<Image
src="/images/sera-01-light.png"
width="2160"
height="1832"
alt="Sera style preview"
className="mt-6 w-full overflow-hidden rounded-2xl border dark:hidden"
/>
<Image
src="/images/sera-01-dark.png"
width="2160"
height="1832"
alt="Sera style preview"
className="mt-6 hidden w-full overflow-hidden rounded-2xl border shadow-sm dark:block"
/>
<span className="sr-only">Try Sera in shadcn/create</span>
</a>
Sera is a typography-first style built on print design principles. It pairs serif headings with sans-serif body text, uses square corners, uppercase tracking, and underlined controls to create an editorial feel for your app.
Like the other new styles, Sera goes beyond theming. It changes the geometry, spacing, and feel of the components so your app starts from a different visual baseline.
Available now in [shadcn/create](/create) for both Radix and Base UI.
<Button asChild size="sm">
<Link href="/create?preset=b4xFeBLg4O" className="mt-6 no-underline!">
Try Sera
</Link>
</Button>

21
apps/v4/content/docs/changelog/2026-04-shadcn-apply.mdx Normal file
View File

@@ -0,0 +1,21 @@
---
title: April 2026 - shadcn apply
description: Switch presets in existing projects without starting over.
date: 2026-04-08
---
We added `shadcn apply` so you can switch presets in an existing project without starting over.
When you run `npx shadcn@latest apply` in an existing project, we apply a new preset, reinstall your existing components, and update your theme, colors, CSS variables, fonts, and icons.
```bash
npx shadcn@latest apply --preset b2D0vQ7G4
```
The CLI keeps the current base and RTL settings from your existing project, even when the preset URL was generated with different values.
<Button asChild size="sm">
<Link href="/create" className="mt-6 no-underline!">
Try a Preset
</Link>
</Button>

63
apps/v4/content/docs/changelog/2026-05-package-imports-target-aliases.mdx Normal file
View File

@@ -0,0 +1,63 @@
---
title: May 2026 - Package Imports and Target Aliases
description: Configure shadcn/ui with package.json imports and portable registry target aliases.
date: 2026-05-05
---
We've added support for package imports and aliases in `files.target` in `shadcn@4.7.0`.
## Package imports
The `shadcn` CLI now supports `package.json#imports` for installing components,
rewriting imports, and resolving third-party registries. You can use private
`#...` import aliases from your `package.json` instead of relying only on
`compilerOptions.paths` in `tsconfig.json`.
```json title="package.json" showLineNumbers
{
"imports": {
"#components/*": "./src/components/*.tsx",
"#lib/*": "./src/lib/*.ts",
"#hooks/*": "./src/hooks/*.ts"
}
}
```
Then use the same roots in `components.json`:
```json title="components.json" showLineNumbers
{
"aliases": {
"components": "#components",
"ui": "#components/ui",
"lib": "#lib",
"hooks": "#hooks",
"utils": "#lib/utils"
}
}
```
This also works in monorepos where app-local files use package imports and
shared UI files are imported from workspace package exports.
See the [package imports guide](/docs/package-imports) for setup details.
## Target aliases
Registry items can now use target aliases in `files[].target` to install files
under the user's configured shadcn directories. For example, the following registry item will install the `prompt-input.tsx` file under the `ui/ai` directory.
```json title="example.json" showLineNumbers
{
"files": [
{
"path": "registry/default/ai/prompt-input.tsx",
"type": "registry:ui",
"target": "@ui/ai/prompt-input.tsx"
}
]
}
```
See the [registry examples](/docs/registry/examples#target-placeholders) for
more details.

120
apps/v4/content/docs/changelog/2026-05-registry-include.mdx Normal file
View File

@@ -0,0 +1,120 @@
---
title: May 2026 - Registry Include and Validate
description: Organize and validate source registries.
date: 2026-05-20
---
This release adds two updates for registry authors:
- `include` for composing large source registries from multiple `registry.json`
files.
- `shadcn registry validate` for checking source registries before publishing.
This makes it easier to maintain source and dynamic registries without keeping
one large `registry.json` file by hand.
Registry authors can now organize a large source registry across multiple
`registry.json` files and compose them with `shadcn build`.
```txt /registry.json/
registry.json
components
└── ui
├── button.tsx
├── input.tsx
└── registry.json
hooks
├── registry.json
├── use-media-query.ts
└── use-toggle.ts
```
{/* prettier-ignore */}
```json title="registry.json" showLineNumbers {6-7}
{
"$schema": "https://ui.shadcn.com/schema/registry.json",
"name": "acme",
"homepage": "https://acme.com",
"include": [
"components/ui/registry.json",
"hooks/registry.json"
]
}
```
Included `registry.json` files are valid registry files for composition and may
omit `name` and `homepage`. Only the root `registry.json` must define the
registry metadata.
```json title="components/ui/registry.json" showLineNumbers
{
"$schema": "https://ui.shadcn.com/schema/registry.json",
"items": [
{
"name": "button",
"type": "registry:ui",
"files": [
{
"path": "button.tsx",
"type": "registry:ui"
}
]
}
]
}
```
## Build output
`shadcn build` resolves included registries and writes a flattened
`registry.json` without `include`. Item file paths are preserved from the root
registry, so a file declared in `components/ui/registry.json` is written as
`components/ui/button.tsx` in the built registry item.
## Validate your registry
You can now validate a source registry before publishing or serving it.
```bash
npx shadcn registry validate
```
Validation runs against the source registry files directly. You do not need to
run `shadcn build` first.
The command checks the root `registry.json`, included registry files, item
schema errors, duplicate item names, include rules, and local item file paths.
Validation reports all actionable errors it can find in one run.
## Registry loaders
The `shadcn/registry` package also exports `loadRegistry` and
`loadRegistryItem` for dynamic registry routes.
```ts title="app/r/registry.json/route.ts" showLineNumbers
import { loadRegistry } from "shadcn/registry"
export async function GET() {
const registry = await loadRegistry()
return Response.json(registry)
}
```
```ts title="app/r/[name].json/route.ts" showLineNumbers
import { loadRegistryItem } from "shadcn/registry"
export async function GET(
_: Request,
{ params }: { params: Promise<{ name: string }> }
) {
const { name } = await params
const item = await loadRegistryItem(name)
return Response.json(item)
}
```
See the [registry.json documentation](/docs/registry/registry-json#include) and
[getting started guide](/docs/registry/getting-started#structure-your-registry)
for more details.

45
apps/v4/content/docs/changelog/2026-05-rhea.mdx Normal file
View File

@@ -0,0 +1,45 @@
---
title: May 2026 - Introducing Rhea
description: A more compact Luma. Smaller spacing. Denser surfaces. Built for focused product interfaces.
date: 2026-05-26
---
Introducing Rhea, a new shadcn/ui style. A more compact Luma. Smaller spacing. Denser surfaces. Built for focused product interfaces.
<a href="/create?preset=b27GcrRo">
<Image
src="/images/rhea-light.png"
width="3840"
height="2160"
alt="Rhea style preview"
className="mt-6 w-full overflow-hidden rounded-2xl border dark:hidden"
/>
<Image
src="/images/rhea-dark.png"
width="3840"
height="2160"
alt="Rhea style preview"
className="mt-6 hidden w-full overflow-hidden rounded-2xl border shadow-sm dark:block"
/>
<span className="sr-only">Try Rhea in shadcn/create</span>
</a>
Rhea started from a simple request we've heard a lot: Luma, but more compact. We looked at how people were using the new styles and what they were asking for, and the pattern was clear. A lot of teams wanted the softness and shape of Luma with tighter spacing, smaller controls, and more information density.
Rhea keeps the same rounded foundation, but makes it more compact for product interfaces where space matters. Buttons, inputs, menus, cards, and lists all sit a little tighter so the UI can carry more without feeling crowded.
## Why a new style?
We considered making this a spacing tweak for Luma, but `--spacing` is a multiplier. Changing it would change what familiar utilities mean across your app. `p-2`, `w-4`, and `m-16` would no longer mean the same size.
That tradeoff felt wrong. Compactness should not force you to relearn Tailwind's spacing scale or wonder whether a utility means something different in one style than another.
So Rhea is a new style instead. It lets us adjust component sizes, gaps, and density directly while keeping the underlying utility scale predictable.
Available now in [shadcn/create](/create) for both Radix and Base UI.
<Button asChild size="sm">
<Link href="/create?preset=b27GcrRo" className="mt-6 no-underline!">
Try Rhea
</Link>
</Button>

61
apps/v4/content/docs/changelog/2026-05-shadcn-eject.mdx Normal file
View File

@@ -0,0 +1,61 @@
---
title: May 2026 - shadcn eject
description: Inline shadcn/tailwind.css and remove the shadcn dependency.
date: 2026-05-31
---
When we added support for both Radix and Base UI, we needed a place for shared Tailwind utilities that both libraries depend on, e.g. custom variants like `data-open:` and `data-closed:` and utilities like `no-scrollbar`.
We also ran into a few bugs while working on RTL support that were easier to fix in one shared place rather than duplicating across every component.
So we created `shadcn/tailwind.css`. When you run `init`, it adds `@import "shadcn/tailwind.css"` to your global CSS file. It works just like other CSS imports such as `tw-animate-css`: a small dependency that is tree-shaken in production and resolved at build time.
If you prefer not to depend on the `shadcn` package for that CSS, we've added the `shadcn eject` command. It inlines `shadcn/tailwind.css` into your global CSS file and removes the `shadcn` dependency from your project.
```bash
npx shadcn@latest eject
```
**Before**
```css
@import "tailwindcss";
@import "tw-animate-css";
@import "shadcn/tailwind.css";
```
**After**
```css
@import "tailwindcss";
@import "tw-animate-css";
/* ejected from shadcn@4.8.3 */
@theme inline {
@keyframes accordion-down {
from {
height: 0;
}
to {
height: var(
--radix-accordion-content-height,
var(--accordion-panel-height, auto)
);
}
}
}
@custom-variant data-open {
&:where([data-state="open"]),
&:where([data-open]:not([data-open="false"])) {
@slot;
}
}
```
In a monorepo, run the command from the workspace that contains your `components.json` and global CSS file:
```bash
npx shadcn@latest eject -c packages/ui
```
See the [CLI documentation](/docs/cli#eject) for more details.

117
apps/v4/content/docs/changelog/2026-06-chat-components.mdx Normal file
View File

@@ -0,0 +1,117 @@
---
title: June 2026 - Components for Chat Interfaces
description: MessageScroller, Message, Bubble, Attachment, and Marker. Components for building chat interfaces.
date: 2026-06-26
---
<ComponentPreview
styleName="radix-rhea"
name="message-scroller-demo"
className="rounded-[34px] sm:rounded-4xl"
previewClassName="h-auto theme-blue bg-surface dark:bg-background p-4 min-[480px]:p-8 min-[560px]:p-10 sm:px-10 sm:py-16"
/>
Today, we’re releasing a new set of components for building chat interfaces:
[**MessageScroller**](/docs/components/message-scroller),
[**Message**](/docs/components/message), [**Bubble**](/docs/components/bubble),
[**Attachment**](/docs/components/attachment), and
[**Marker**](/docs/components/marker).
This is the first phase of the chat components work. We’re taking it one piece at a time, reimagining the abstraction behind each part, and shipping them as shadcn/ui components you can copy, compose, and adapt to your product.
We are starting with the conversation layer: scrolling, message rows, bubbles, attachments, and markers.
We asked ourselves: what makes a great streaming chat experience? Then we abstracted the core rules into a set of primitives: `MessageScroller`.
```bash
npx shadcn@latest add message-scroller message bubble attachment marker
```
## MessageScroller
`MessageScroller` is the scroll container for a conversation. It handles the
parts that are easy to get wrong: anchored turns, streamed replies, saved thread
restore, prepended history, jump-to-message, scroll controls, and visibility
tracking.
`MessageScroller` owns that behavior without owning your messages, AI state,
transport, persistence, or model state. You bring the content renderer.
The `MessageScroller` is also available as an unstyled headless component in `@shadcn/react`.
## Message, Bubble, Attachment, and Marker
The rest of the components cover the everyday pieces you need around the
scroller.
- `Message` lays out a row in the conversation with avatar, alignment, header,
content, footer, and grouped messages.
- `Bubble` renders the message surface, with variants, alignment, reactions,
links, buttons, and collapsible content.
- `Attachment` renders files and images with media, metadata, upload state,
actions, and a full-card trigger that keeps actions separately clickable.
- `Marker` renders status updates, system notes, bordered rows, and labeled
separators for things like streaming state, tool activity, and date breaks.
They are intentionally small. Compose them together for AI chats, support
inboxes, team threads, group chats, and product-specific conversations.
## scroll-fade and shimmer
We also added two new CSS utilities for the details that make chat interfaces
feel better.
[`scroll-fade`](/docs/utils/scroll-fade) adds scroll-aware edge fades to scroll
containers. Use it on `MessageScroller`, `ScrollArea`, attachment rows, and any
long list where you want to hint at more content without adding overlays or
scroll listeners.
<ComponentPreview
styleName="radix-rhea"
name="scroll-fade-demo"
previewClassName="h-auto"
/>
[`shimmer`](/docs/utils/shimmer) adds a text shimmer for live status. Use it
for things like "Thinking…", "Generating response…", running tools, and
streaming markers.
<ComponentPreview styleName="radix-rhea" name="shimmer-demo" />
Both utilities ship with `shadcn/tailwind.css`, so projects initialized with
`npx shadcn@latest init` already have them.
## @shadcn/react
We also created `@shadcn/react`, a new package for unstyled, headless React
components.
The first primitive is `@shadcn/react/message-scroller`. The registry component
wraps it with shadcn/ui styles, but the scroll behavior lives in the package:
anchoring, auto-follow, prepend preservation, scroll commands, and visibility.
This lets us ship behavior without locking it to a visual style. You still get
copy-and-paste components that match your project, and the hard interaction
logic stays tested in one place.
Available now for Radix and Base UI.
## AI Elements
This does not replace [AI Elements](https://ai-sdk.dev/elements/overview). You
can keep using AI Elements for AI interface components and patterns. This
release is about bringing the core pieces of chat into shadcn/ui, one component
at a time.
If you are already using a component from AI Elements, you do not need to
rewrite your app. Keep what works. Try the shadcn/ui version when you want the
newer abstraction, the updated styling, or support across Radix and Base UI.
The goal is to make these pieces easy to adopt independently. Replace one part,
compose it with what you already have, and keep building.
<Button asChild size="sm">
<Link href="/docs/components" className="mt-6 no-underline!">
View Components
</Link>
</Button>

98
apps/v4/content/docs/changelog/2026-06-github-registries.mdx Normal file
View File

@@ -0,0 +1,98 @@
---
title: June 2026 - GitHub Registries
description: Turn any public GitHub repository into a shadcn registry.
date: 2026-06-01
---
**You can now turn any public GitHub repository into a registry.**
Add a `registry.json` file at the root of the repository, define the items you
want to distribute, and users can install them directly from GitHub with the
`shadcn` CLI.
```bash
npx shadcn@latest add <username>/<repo>/<item>
```
For example, to install the `project-conventions` item from the `acme/toolkit` repository:
```bash
npx shadcn@latest add acme/toolkit/project-conventions
```
GitHub registries are source registries. You do not need to run `shadcn build`,
publish generated item JSON files or set up a registry server. The CLI reads the
root `registry.json`, resolves `include` entries, finds the requested item and
installs the files declared by that item.
## Distribute anything
Registry items are not limited to components. A GitHub registry can distribute
components, hooks, utilities, design tokens, feature kits, project conventions,
agent instructions, testing setup, CI workflows, release workflows, templates,
codemods, migration kits and other project files.
For example, a repository can expose a `project-conventions` item that installs
shared docs, editor settings and agent instructions:
```json title="registry.json" showLineNumbers
{
"$schema": "https://ui.shadcn.com/schema/registry.json",
"name": "acme-toolkit",
"homepage": "https://github.com/acme/toolkit",
"items": [
{
"name": "project-conventions",
"type": "registry:item",
"files": [
{
"path": "AGENTS.md",
"type": "registry:file",
"target": "~/AGENTS.md"
},
{
"path": ".editorconfig",
"type": "registry:file",
"target": "~/.editorconfig"
},
{
"path": "docs/conventions.md",
"type": "registry:file",
"target": "~/docs/conventions.md"
}
]
}
]
}
```
## Commands
GitHub registry addresses work with the same commands as other registry
addresses.
List items from a GitHub registry:
```bash
npx shadcn@latest list acme/toolkit
```
Search items:
```bash
npx shadcn@latest search acme/toolkit --query conventions
```
View an item:
```bash
npx shadcn@latest view acme/toolkit/project-conventions
```
Install an item:
```bash
npx shadcn@latest add acme/toolkit/project-conventions
```
See the [GitHub Registries](/docs/registry/github) docs for the full guide.

125
apps/v4/content/docs/changelog/2026-07-base-ui-default.mdx Normal file
View File

@@ -0,0 +1,125 @@
---
title: July 2026 - Base UI as the Default
description: New projects now use Base UI by default. Radix is still fully supported.
date: 2026-07-02
---
Starting today, **Base UI is the default component library in shadcn/ui**.
<div className="mt-6 flex w-full items-center justify-center rounded-2xl bg-muted/50 py-32 text-foreground ring ring-border dark:bg-muted">
<svg width="17" height="24" viewBox="0 0 17 24" className="size-16">
<path
fill="currentColor"
d="M9.5001 7.01537C9.2245 6.99837 9 7.22385 9 7.49999V23C13.4183 23 17 19.4183 17 15C17 10.7497 13.6854 7.27351 9.5001 7.01537Z"
/>
<path
fill="currentColor"
d="M8 9.8V12V23C3.58172 23 0 19.0601 0 14.2V12V1C4.41828 1 8 4.93989 8 9.8Z"
/>
</svg>
</div>
First, a bit of history. When shadcn/ui launched in January 2023, it was built on Radix. At the time, nothing else came close. Unstyled headless components, great APIs, great accessibility, battle-tested in millions of apps.
Fast forward a few years and the same folks who built Radix are building something new: [Base UI](https://www.base-ui.com). They've done it once. Now they get to do it again, with everything they learned the first time.
Last year, Base UI tagged a beta and a lot of you asked if we are going to replace Radix with it. I said "the worst thing you can do for your production app is switch component libraries". I meant it, and it still holds. So instead of switching, we did the shadcn thing: we rebuilt every component for Base UI, kept the same abstraction, and let you choose. December brought `npx shadcn create` with both libraries. January brought full Base UI docs.
Then we watched what you did with it.
---
## Why Now
- **Base UI is stable.** It's at 1.6.0 with 6M+ weekly downloads.
- **It keeps getting better.** The team ships new and useful components regularly.
- **We use it.** Every new project we've started runs on Base UI.
- **You use it.** Projects created on shadcn/create now pick Base UI over Radix 2 to 1.
The community already made the call. We're making it official.
---
## What's Changed
- **New projects default to Base UI.** Run `npx shadcn init` and Base UI is the default pick.
- **shadcn/create shows Base UI first.**
- **The docs default to Base UI.** Component pages open on the Base UI tab. Radix docs are one click away.
## What This Means for You
**Radix is not being deprecated.** We still support it, and every update and new component will ship for both libraries (unless a component only exists in Base UI).
**You do not need to migrate.** Radix is a mature, tested library. We still run it in production today and we're not migrating. If your app works, keep shipping.
**Prefer Radix for new projects?** It's one flag away:
```bash
npx shadcn init -b radix
```
If you have scripts or CI running `shadcn init` non-interactively and expecting Radix, add `-b radix` to keep them on the same path.
**Building a registry?** Ship a `registry:base` config if you want to pin a specific library. Items without one now init as Base UI.
**Starting something new?** We recommend Base UI.
## When You're Ready to Migrate
You don't need to migrate. But if you want to, we built a skill for it:
```bash
npx skills add shadcn/ui
```
Then ask your coding agent:
```txt
migrate accordion to base-ui
```
It's progressive by default: migrate one component and its usage at a time while your project stays green and shippable. Both libraries coexist while you work. Stop halfway, ship, come back next week and it picks up where you left off. Or ask for the whole project in one go.
### Why a skill and not a codemod?
Because you own the code. You've added variants, changed classes, threaded new props. A codemod handles the components you never touched and breaks on the ones you did.
So we shipped knowledge instead: every rename, every prop change, every behavior difference, hand-checked against both libraries. Your agent reads it, figures out what _you_ changed, and carries those changes over.
Mechanical things get fixed everywhere (`asChild` is now `render`). Behavior changes get flagged, never silently patched. You decide.
### What a migration produces
Every run leaves three things:
- **Working code.** Typechecked and built before it reports success.
- **A report per component** in `.migration/` at your project root: what changed, what was left alone, and a short checklist of things to verify by hand.
- **Clean git history.** One commit per component, on a branch. Rollback is deleting the branch.
Here's what a report looks like:
```md title=".migration/accordion.md"
# accordion
<!-- date, strategy used, and the one-line verdict -->
## Changed
<!-- every file touched, with what changed and why -->
## Left alone
<!-- files that look related but were intentionally not touched -->
## Behavior changes
<!-- differences that compile fine but act differently. flagged, not patched -->
## Verify by hand
<!-- a short checklist: open, click, tab through. takes a minute -->
```
No hidden state. Progress lives in your files and git history, so any agent, any session, any day picks up where the last one stopped.
It works with Claude Code, Cursor, or any agent that supports skills. We tested it on real projects: 60+ components, 36 of them on Radix. A full migration ran in about 25 minutes at roughly 10k tokens per component. Clean builds, customizations intact.

44
apps/v4/content/docs/changelog/2026-07-dynamic-search.mdx Normal file
View File

@@ -0,0 +1,44 @@
---
title: July 2026 - Dynamic Search
description: Registries can now handle search server-side.
date: 2026-07-31
---
**Registries can now handle search server-side.**
When you run `shadcn search`, the CLI forwards the search parameters to your
registry as query params:
```txt
GET /r/registry.json?q=button&limit=50&offset=0
```
Return the matching items with a `pagination` object and the CLI uses your
results as-is. This makes search fast for large registries: no more downloading
the full catalog to search it.
```json title="registry.json?q=button&limit=1"
{
"name": "acme",
"homepage": "https://acme.com",
"items": [
{
"name": "button",
"type": "registry:ui",
"description": "A button component."
}
],
"pagination": {
"total": 12,
"offset": 0,
"limit": 1,
"hasMore": true
}
}
```
Dynamic search is opt-in. Static registries ignore the query params and keep
working without any changes.
See the [Dynamic Search](/docs/registry/dynamic-search) docs for the full
guide.

88
apps/v4/content/docs/changelog/2026-07-helpers.mdx Normal file
View File

@@ -0,0 +1,88 @@
---
title: July 2026 - Introducing @shadcn/helpers
description: Small, focused helpers for developing apps, starting with AI SDK and TanStack AI.
date: 2026-07-14
---
We are open sourcing **@shadcn/helpers**, a new package for small, focused
helpers that make developing apps easier.
Starting with a helper for AI SDK and TanStack AI. It lets you write a
conversation in code, then run it through the real `useChat` lifecycle without
a model, API route, network request, or API key.
Your UI receives native
framework messages and streaming events, so reasoning, tool calls, loading
states, and message components behave the same way they do in production.
Here is a conversation written with the AI SDK helper:
```ts showLineNumbers
import { createChat } from "@shadcn/helpers/ai-sdk"
const chat = createChat()
.user("What changed in this release?")
.assistant("The release adds keyboard shortcuts and faster search.")
.user("Can you check the full release notes?")
.sleep(500)
.assistant(({ writer }) => {
writer.stepStart()
// Reasoning.
writer.reasoning("I should read the release notes first.")
// Tool call.
writer
.tool("getReleaseNotes", {
title: "Reading release notes",
input: { version: "latest" },
})
.sleep(500)
.output({
highlights: ["Keyboard shortcuts", "Faster search"],
})
// Source.
writer.sourceUrl({
title: "Release notes",
url: "https://example.com/releases",
})
// Response.
writer.text("The release adds keyboard shortcuts and faster search.")
})
```
Pass its messages and transport to `useChat`:
```tsx showLineNumbers
import { useChat } from "@ai-sdk/react"
const initialMessages = chat.get(0)
const transport = chat.transport()
export function Chat() {
const { messages } = useChat({
messages: initialMessages,
transport,
})
}
```
The package includes two adapters:
- [`@shadcn/helpers/ai-sdk`](/docs/helpers/ai-sdk) plugs into AI SDK's `useChat`
as a transport.
- [`@shadcn/helpers/tanstack-ai`](/docs/helpers/tanstack-ai) plugs into TanStack
AI's `useChat` as a connection and streams real AG-UI events.
Use it to build components, create previews and demos, write documentation, or
test streaming interfaces with deterministic output and no backend dependency.
<div className="flex flex-wrap gap-2">
<Button asChild size="sm">
<Link href="/docs/helpers/ai-sdk" className="mt-6 no-underline!">
Read the Docs
</Link>
</Button>
</div>

55
apps/v4/content/docs/changelog/2026-07-react-aria.mdx Normal file
View File

@@ -0,0 +1,55 @@
---
title: July 2026 - React Aria
description: React Aria is now available as a component base in shadcn/ui.
date: 2026-07-17
---
**React Aria** is now a first-class component base in shadcn/ui.
Build with React Aria Components alongside Base UI and Radix. Pick it in
shadcn/create or initialize a project with `--base aria`. The CLI handles the
dependencies, registry resolution, styles, and component installation.
<div className="mt-6 flex w-full items-center justify-center rounded-2xl bg-muted/50 py-32 text-foreground ring ring-border dark:bg-muted">
<svg viewBox="200 206 800 790" fill="none" className="size-16">
<path
fill="currentColor"
d="M720.67 205.995C867.583 205.995 986.679 325.091 986.68 472.003C986.68 590.753 908.865 691.325 801.446 725.521L979.312 948.055C994.438 966.98 980.963 995 956.736 995H795.612C778.743 995 762.715 987.629 751.734 974.823L697.365 911.421L493.126 653.39C457.134 607.918 489.518 540.979 547.511 540.977L720.67 540.971C758.758 540.971 789.635 510.091 789.635 472.003C789.634 433.915 758.758 403.038 720.67 403.038H429.939C404.955 403.038 388.623 391.886 373.994 373.623L277.349 252.966C262.194 234.045 275.664 205.996 299.905 205.995H720.67Z M396.605 720.706C407.798 705.406 430.443 704.843 442.381 719.568L503.816 797.018H502.786L535.569 838.934C548.074 854.358 549.943 877.191 538.047 893.09L476.638 972.545C465.692 986.707 448.803 995 430.903 995H242.276C218.18 995 204.665 967.248 219.523 948.278L337.992 797.018H337.923L396.605 720.706Z"
/>
</svg>
</div>
## What's New
- **A first-class React Aria base** - Choose React Aria anywhere you can choose
Base UI or Radix, including the CLI, presets, and shadcn/create.
- **Full component documentation** - React Aria components have dedicated
installation, usage, composition, examples, and API reference sections.
- **All eight styles** - Use React Aria with Vega, Nova, Maia, Lyra, Mira, Luma,
Rhea, or Sera.
- **Base-specific output** - React Aria state selectors and dependencies are
scoped to the Aria registry. Existing Base UI and Radix components are
unchanged.
## Start with React Aria
Use the `aria` base when initializing a project:
```bash
npx shadcn@latest init --base aria
```
Or choose **React Aria** in [shadcn/create](/create?base=aria). Once the project
is initialized, `shadcn add` installs the React Aria implementation for each
component.
Base UI remains the default, and Radix remains fully supported. Existing
projects stay on their current base.
<div className="flex flex-wrap gap-2">
<Button asChild size="sm">
<Link href="/create?base=aria" className="mt-6 no-underline!">
Create a React Aria project
</Link>
</Button>
</div>

17
apps/v4/content/docs/changelog/2026-07-toast.mdx Normal file
View File

@@ -0,0 +1,17 @@
---
title: July 2026 - Toast
description: A new Toast component built on Base UI primitives.
date: 2026-07-23
---
A new [Toast](/docs/components/base/toast) component is now available for Base
UI projects. It supports actions, status types, promises, stacking, and swipe
dismissal.
<ComponentPreview styleName="base-nova" name="toast-demo" />
Add it to your project with the CLI:
```bash
npx shadcn@latest add toast
```

52
apps/v4/content/docs/changelog/2026-07-typeset.mdx Normal file
View File

@@ -0,0 +1,52 @@
---
title: July 2026 - Introducing shadcn/typeset
description: A complete typography system for HTML, from blog posts to streaming chat. One CSS file you own.
date: 2026-07-10
---
Today we're releasing **shadcn/typeset**: a styling system for HTML and rendered markdown, in one CSS file.
Your app renders the same HTML elements everywhere: headings, paragraphs, lists, tables, and code. You style them for your blog, then your docs, and now chat. Typeset lets you style them once, then tune the rhythm for each context.
```tsx
<div className="typeset">{content}</div>
```
Add one class and everything inside gets styled. Typeset follows the size of its container, uses your theme, and gives you three controls: size, leading, and flow.
You can create as many typesets as you need. Use a tighter rhythm for chat and a roomier one for docs:
```css
.typeset-chat {
--typeset-leading: 1.6;
--typeset-flow: 1em;
}
.typeset-docs {
--typeset-size: 15px;
--typeset-leading: 1.75;
--typeset-flow: 1.5em;
}
```
```tsx
<div className="typeset typeset-chat">{message}</div>
<article className="typeset typeset-docs">{page}</article>
```
It's also designed for streaming, so new blocks don't restyle earlier ones. The file lives in your project. There's no package or config layer to work around.
Open the [typeset builder](/typeset) to create yours, or read the [Typeset docs](/docs/typeset) for the full guide.
<div className="flex gap-2">
<Button asChild size="sm">
<Link href="/typeset" className="mt-6 no-underline!">
Build your typeset
</Link>
</Button>
<Button asChild size="sm" variant="outline">
<Link href="/docs/typeset" className="mt-6 no-underline!">
Read the docs
</Link>
</Button>
</div>

62
apps/v4/content/docs/changelog/2026-08-helpers-human-in-the-loop.mdx Normal file
View File

@@ -0,0 +1,62 @@
---
title: August 2026 - Human in the Loop
description: Mock paused tool calls, approvals, and continuations for the AI SDK with @shadcn/helpers.
date: 2026-08-12
---
**@shadcn/helpers** can now mock human-in-the-loop flows for the AI SDK. A
scripted conversation can pause for real user input, wait for an approval, and
continue with whatever the user decided.
Everything streams through the real
`useChat` lifecycle, so your tool cards, approval prompts, and question flows
behave exactly as they would in production.
```ts showLineNumbers
import { createChat } from "@shadcn/helpers/ai-sdk"
const chat = createChat<ChatMessage>()
.user("Help me plan the next prototype.")
.assistant(({ writer }) => {
writer.text("A couple of questions before I start.")
writer.tool("askQuestions", { input: { questions } })
})
.assistant(({ writer, toolCall }) => {
writer.text(
toolCall?.name === "askQuestions" && toolCall.output
? `Starting with ${toolCall.output.answers.direction}.`
: "Starting now."
)
})
```
Pass `needsApproval` to pause behind the user's decision. The scripted output
streams after approval, and denial streams automatically.
```ts showLineNumbers
chat
.assistant(({ writer }) => {
writer.text("That will archive 3 drafts. I need your approval.")
writer.tool("archiveDrafts", {
input: { count: 3 },
needsApproval: true,
output: { archived: 3 },
})
})
.assistant(({ writer, toolCall }) => {
writer.text(
toolCall?.approved ? "Archived 3 drafts." : "Okay, leaving them in place."
)
})
```
<div className="flex flex-wrap gap-2">
<Button asChild size="sm">
<Link
href="/docs/helpers/ai-sdk#human-in-the-loop"
className="mt-6 no-underline!"
>
Read the Docs
</Link>
</Button>
</div>

83
apps/v4/content/docs/changelog/2026-08-private-github-registries.mdx Normal file
View File

@@ -0,0 +1,83 @@
---
title: August 2026 - Private GitHub Registries
description: Install registry items from private GitHub repositories using the GitHub CLI or a token.
date: 2026-08-24
---
**GitHub registries now work with private repositories.**
In June, we made it possible to turn any public GitHub repository into a
registry. Teams asked for the same thing for their internal code: design
systems, feature kits, agent rules and conventions that should not be public.
You can now install from private repositories. If you can read the repository,
the CLI can install from it.
```bash
npx shadcn@latest add acme/internal-toolkit/auth-kit
```
## Zero configuration
If you are logged in to the GitHub CLI, there is nothing to set up.
```bash
gh auth login
```
When a repository is not publicly readable, the CLI reads it through `gh` using
your stored credentials. The token stays inside the GitHub CLI. It never enters
the shadcn process.
```txt
✔ Using gh credentials.
✔ Checking registry.
✔ Created 1 file:
- lib/auth.ts
```
## CI support
Where the GitHub CLI is not installed, set `GH_TOKEN` or `GITHUB_TOKEN`:
```bash
GH_TOKEN=github_pat_xxx npx shadcn@latest add acme/internal-toolkit/auth-kit
```
We recommend a fine-grained personal access token scoped to the repository with
**Contents: Read-only** access.
## Works with every command
Private repositories work with the same commands as public GitHub registries.
```bash
npx shadcn@latest list acme/internal-toolkit
```
```bash
npx shadcn@latest search acme/internal-toolkit --query auth
```
```bash
npx shadcn@latest view acme/internal-toolkit/auth-kit
```
```bash
npx shadcn@latest registry validate acme/internal-toolkit
```
## How it works
- Public repositories are read anonymously, exactly as before. No credentials
are used and the GitHub CLI is never invoked.
- The CLI tries anonymous access first and only uses your credentials when the
repository is not publicly readable.
- Private files are read through GitHub's Contents API, pinned to the resolved
commit SHA.
- A token from `GH_TOKEN` is only ever sent to `api.github.com`. Stored GitHub
CLI credentials are read by `gh`, not by the CLI.
See the
[Private repositories](/docs/registry/github#private-repositories) docs for
the full guide.

52
apps/v4/content/docs/changelog/2026-08-questionnaire.mdx Normal file
View File

@@ -0,0 +1,52 @@
---
title: August 2026 - Questionnaire
description: A new component for building multi-step question flows with fixed, freeform, multiple, and skippable answers.
date: 2026-08-05
---
Today, we're releasing [**Questionnaire**](/docs/components/base/questionnaire),
a new component for multi-step question flows. Use it for agent clarification
prompts, onboarding, surveys, intake forms, and configuration.
Questionnaire is available for Base UI, React Aria, and Radix across all eight
styles.
<ComponentPreview
align="end"
styleName="base-nova"
name="questionnaire-demo"
previewClassName="min-h-[560px] p-4 sm:p-8"
/>
## Features
- Single and multiple selection with native radios and checkboxes.
- Freeform answers alongside fixed choices.
- Explicit skipping for optional questions.
- Previous, next, submit, and custom progress controls.
- Required and custom validation.
- Controlled navigation, saved defaults, and conditional questions.
- Keyboard navigation with optional letter or number shortcuts.
- Native form serialization and server-rendered collection state.
- Standalone, Card, and Dialog composition.
## Installation
```bash
npx shadcn@latest add questionnaire
```
## @shadcn/react
The `<Questionnaire />` component is also available as an unstyled headless primitive in `@shadcn/react`. [Read the docs](/docs/react/questionnaire) to learn more.
<div className="flex flex-wrap gap-2">
<Button asChild size="sm">
<Link
href="/docs/components/base/questionnaire"
className="mt-6 no-underline!"
>
View Questionnaire
</Link>
</Button>
</div>

53
apps/v4/content/docs/changelog/2026-09-cn.mdx Normal file
View File

@@ -0,0 +1,53 @@
---
title: September 2026 - cn
description: Components now import cn from the cn package. One dependency instead of two, and no local helper to maintain.
date: 2026-09-03
---
**Every shadcn component now imports `cn` from the `cn` package.**
For years, every shadcn project started with the same five lines in
`lib/utils.ts`: import `clsx`, import `twMerge`, wrap one in the other, export
it as `cn`. It worked, but it meant two dependencies and a helper you had to
copy into every project and every registry.
We have moved that into a package. [`cn`](https://github.com/shadcn-ui/cn) is a
drop-in replacement for `twMerge(clsx(...))`. It is smaller, faster and ships
the same API, so nothing changes at the call site.
```tsx
import { cn } from "cn"
;<div className={cn("flex items-center", className)} />
```
## What changed
- Registry components, blocks and examples import `cn` from `cn` instead of
`@/lib/utils`.
- `npx shadcn init` installs `cn` and generates a one-line `lib/utils.ts`.
- Every registry item that uses `cn` declares it as a dependency, so
`npx shadcn add` installs it in projects created before this change.
## lib/utils.ts
The `utils` registry item still exists. It now re-exports `cn` so your own code
keeps working and you still have a single place for project helpers.
```ts title="lib/utils.ts"
export { cn } from "cn"
```
## Existing projects
Nothing breaks. Your `lib/utils.ts` keeps working and new components install
`cn` next to it. To move the rest of your project over and drop `clsx` and
`tailwind-merge`, run the migration:
```bash
npx shadcn@latest migrate cn
```
It rewrites imports, replaces `twMerge(clsx(...))` calls and removes the old
packages when nothing references them anymore. See the
[CLI docs](/docs/cli#migrate-cn) for details.

6
apps/v4/content/docs/changelog/index.mdx Normal file
View File

@@ -0,0 +1,6 @@
---
title: Changelog
description: Latest updates and announcements.
---
Latest updates and announcements for shadcn/ui.

4
apps/v4/content/docs/changelog/meta.json Normal file
View File

@@ -0,0 +1,4 @@
{
"title": "Changelog",
"pages": []
}