shadcn - freeCodeCamp.org

How to Build a Shadcn Sheet Component in React: Cart and Filter Panel Examples

Vaibhav Gupta — Mon, 13 Jul 2026 14:13:49 +0000

A Sheet is a panel that slides in from the edge of the screen instead of popping up in the center like a modal. You've likely used one when you've opened a shopping cart on an e-commerce site or tapped a filter icon and watched options slide in from the side.

Building a Sheet that scrolls correctly with long content, keeps a header and footer fixed in place, and manages form or counter state without bugs takes more than wrapping a

in a slide animation.

In this tutorial, you'll build two production-ready Sheet components using shadcn/ui and Base UI primitives via Shadcn Space:

A Shopping Cart Sheet with quantity controls, item removal, and a live subtotal.
A Filter Panel Sheet with category checkboxes, a price range slider, star ratings, and an active filter count.

By the end, you'll have both components running in your project, and you'll understand the state and layout decisions behind them well enough to build your own Sheet variants from scratch.

Prerequisites
What You'll Build
How to Set Up the CLI Registry
How to Build the Shopping Cart Sheet (sheet-03)
How to Build the Filter Panel Sheet (sheet-04)
Quick Reference Table
Key Concepts Recap
Conclusion
Resources

Prerequisites

Before you start, make sure you have:

Node.js 18 or higher installed
shadcn/ui initialized in your project (npx shadcn@latest init)
Basic knowledge of React and TypeScript

If you haven't initialized shadcn/ui yet, run npx shadcn@latest init in your project root and follow the prompts before continuing.

What You'll Build

This tutorial uses components installed through the Shadcn Space registry, an open-source collection of production-ready components and UI blocks for shadcn/ui.

You can browse the full set in the Shadcn Sheet component library. Each component supports both Radix UI and Base UI primitives and includes a Copy Prompt option, so you can paste the component spec into tools like v0, Lovable, or Bolt if you're prototyping. This tutorial uses the Base UI versions.

Shopping Cart Sheet (sheet-03)

Slide-in panel from the right with a cart icon trigger and item-count badge
Quantity increment, decrement, and removal per item
Live subtotal and total calculated from cart state
Fixed header and footer with a scrollable item list in between

Filter Panel Sheet (sheet-04)

Slide-in panel from the left
Multi-select category checkboxes
Price range slider with live min/max display
Single-select star rating filter
Active filter count badge and a "Clear All" action that doesn't close the panel

How to Set Up the CLI Registry

Before running any install commands, register the Shadcn Space registry in your components.json file.

Open components.json in your project root and add the registries field:

{
  "registries": {
    "@shadcn-space": {
      "url": "https://shadcnspace.com/r/{name}.json"
    }
  }
}

This tells the shadcn CLI where to resolve components prefixed with @shadcn-space/. Without this step, the install commands below will fail.

For a full walkthrough of registry setup, see the getting started guide. Shadcn Space also ships an MCP server, so you can browse and install components straight from your editor if your workflow uses MCP tooling. If you prefer following along visually with a video, here you go:

How to Build the Shopping Cart Sheet (sheet-03)

What the Cart Sheet Does

The cart icon sits in your navbar. Clicking it slides a panel in from the right showing each item's image, name, variant, and price, with controls to change quantity or remove the item entirely. The subtotal updates as you go, and the footer stays pinned at the bottom regardless of how many items are in the list.

How to Install the Cart Sheet

Run one of the following based on your package manager:

npm:

npx shadcn@latest add @shadcn-space/sheet-03

pnpm:

pnpm dlx shadcn@latest add @shadcn-space/sheet-03

Yarn:

yarn dlx shadcn@latest add @shadcn-space/sheet-03

Bun:

bunx --bun shadcn@latest add @shadcn-space/sheet-03

The CLI copies the component into your project at:

components/
  shadcn-space/
    sheet/
      sheet-03.tsx

The Component Code

"use client";
import { useState } from "react";
import { ShoppingCartIcon, PlusIcon, MinusIcon, Trash2Icon } from "lucide-react";
import {
  Sheet,
  SheetTrigger,
  SheetContent,
  SheetHeader,
  SheetTitle,
  SheetDescription,
  SheetFooter,
  SheetClose,
} from "@/components/ui/sheet";
import { Button } from "@/components/ui/button";
import { ButtonGroup, ButtonGroupText } from "@/components/ui/button-group";
import { Badge } from "@/components/ui/badge";
import { Separator } from "@/components/ui/separator";

const initialItems = [
  {
    id: 1,
    name: "Apple Watch S9",
    variant: "Midnight / 41mm",
    price: 684.0,
    qty: 1,
    image: "https://images.shadcnspace.com/assets/ecommerce/product-category/product-category-03-1.webp",
  },
  {
    id: 2,
    name: "Beige Jacket",
    variant: "Size M / Beige",
    price: 479.0,
    qty: 1,
    image: "https://images.shadcnspace.com/assets/ecommerce/product-category/product-category-02-2.webp",
  },
  {
    id: 3,
    name: "Glow Serum",
    variant: "30ml / Vitamin C",
    price: 46.0,
    qty: 2,
    image: "https://images.shadcnspace.com/assets/ecommerce/product-category/product-category-03-3.webp",
  },
];

const ShoppingCartDemo = () => {
  const [items, setItems] = useState(initialItems);

  const updateQty = (id, delta) => {
    setItems((prev) =>
      prev
        .map((item) => (item.id === id ? { ...item, qty: item.qty + delta } : item))
        .filter((item) => item.qty > 0)
    );
  };

  const subtotal = items.reduce((sum, item) => sum + item.price * item.qty, 0);
  const totalCount = items.reduce((sum, item) => sum + item.qty, 0);

  return (
    
      }>
        
        {totalCount > 0 && (
          
            {totalCount}
          
        )}
      

      
        
          Your Cart
          
            {totalCount > 0
              ? `${totalCount} item${totalCount > 1 ? "s" : ""} in your cart`
              : "Your cart is empty"}
          
        

        
          {items.map((item) => (
            
              
                
              
              
                {item.name}
                {item.variant}
                ${item.price.toFixed(2)}
              
              
                
                
                  
                  {item.qty}
                  
                
              
            
          ))}
        

        
          
            
              Subtotal
              ${subtotal.toFixed(2)}
            
            
              Shipping
              Free
            
            
            
              Total
              ${subtotal.toFixed(2)}
            
          
          
          }>
            Continue Shopping
          
        
      
    
  );
};

export default ShoppingCartDemo;

Let's go through how this works.

1. Derived totals instead of tracked state

subtotal and totalCount are calculated from items on every render, not stored in their own useState. If you tracked them separately, they'd drift out of sync the first time you updated items and forgot to update the count alongside them.

2. Removing an item is just zeroing its quantity

const updateQty = (id, delta) => {
  setItems((prev) =>
    prev
      .map((item) => (item.id === id ? { ...item, qty: item.qty + delta } : item))
      .filter((item) => item.qty > 0)
  );
};

The trash icon calls updateQty(item.id, -item.qty), which drops that item's quantity to zero. The .filter() step then removes it from the array. This means you don't need a separate "remove item" function that duplicates logic already living in updateQty.

3. `render` prop instead of `asChild`

SheetTrigger and SheetClose use the render prop (render={}>Apply Filters ); }; export default AdvancedFiltersDemo;

How this component works:

1. Use a separate state for each filter type

Categories and availability use arrays because users can select multiple options. Rating stores a single value (or null) since only one rating can be selected. Price uses a two-value array ([min, max]) to store the selected range. This keeps each filter's state simple and matches how the UI works.

2. `activeCount` is computed, not tracked

Same reasoning as the cart badge above:

const activeCount =
  selectedCategories.length +
  (priceRange[0] !== 0 || priceRange[1] !== 1000 ? 1 : 0) +
  (selectedRating !== null ? 1 : 0) +
  selectedAvailability.length;

If you tracked this count manually, you'd eventually add a new filter, forget to update the count logic, and end up with a badge that lies to the user.

3. "Apply Filters" closes the panel, "Clear All" doesn't

Clear All calls clearAll() directly on a plain Button. Apply Filters is wrapped in SheetClose, so it resets nothing but closes the panel. A user clearing filters usually wants to keep the panel open to pick new ones. Closing on every action would force them to reopen it each time.

4. Toggling a category with `.filter()` and spread

const toggleCategory = (cat) =>
  setSelectedCategories((prev) => (prev.includes(cat) ? prev.filter((c) => c !== cat) : [...prev, cat]));

This one line handles both adding and removing a category from the array, based on whether it's already present. It's a pattern worth reusing anywhere you have a multi-select checkbox list backed by an array of strings.

Live Preview:

Quick Reference Table

Sheet	Identifier	Use Case
Shopping Cart Sheet	sheet-03	Cart drawers, order summaries
Filter Panel Sheet	sheet-04	Product filters, search refinement panels

To install either, swap the identifier in the CLI command:

npx shadcn@latest add @shadcn-space/

Key Concepts for Using Shadcn Sheet

Use a Sheet for secondary workflows: It's ideal for filters, shopping carts, settings, navigation menus, and forms that shouldn't interrupt the main page.
Keep the layout consistent: Use a fixed header, a scrollable content area (flex-1 overflow-y-auto), and a fixed footer so actions remain visible even with long content.
Derive UI values from state: Counts, totals, and badges (such as active filters or cart items) should be calculated from state instead of being stored separately.
Close the Sheet after completing an action: Actions like Apply Filters, Save, or Checkout should close the Sheet. Actions like Clear Filters or Reset should keep it open so users can continue making changes.
Choose the right state structure: Use arrays for multi-select options (such as categories or availability), a single value (or null) for single-select options (such as ratings), and a two-value array ([min, max]) for range filters like price.
Keep actions easy to reach: Place primary actions like Apply, Save, or Checkout in the footer so they remain accessible while the content scrolls.
Avoid overloading the Sheet: If the workflow is long, requires multiple steps, or needs the user's full attention, consider using a dedicated page instead of a Sheet.

Conclusion

In this guide, we built two practical Shadcn Sheet components, a shopping cart and a filter panel, to demonstrate the patterns you'll use most often in React applications. Along the way, we covered layout best practices, state management, derived values, and interaction patterns that make Sheets feel intuitive and reliable.

These examples are more than just demos. They provide a reusable foundation for building settings drawers, mobile navigation, notification panels, and many other side panel experiences. By following these patterns, you can create Shadcn Sheet components that are clean, responsive, and easy to maintain as your application grows.

Resources

Shadcn UI: Component library and documentation home
Shadcn Sheet Components: All Sheet variants are available in Radix and Base UI
Shadcn Components: Full component library with all available categories
Shadcn Dashboard: Ready-to-use admin dashboard built on the same system
Shadcn Sidebar: If you're looking for a shadcn sidebar to pair with these panels, this is where to start
How to Use the Shadcn CLI: Getting started guide for the CLI and registry setup
Shadcn MCP Server: Browse and install components from your editor
Video Walkthrough: How to Use Shadcn Space with MCP Server
Official shadcn/ui Documentation

How to Build Production-Ready Card Components with shadcn/ui

Vaibhav Gupta — Tue, 07 Jul 2026 16:00:40 +0000

Card components are one of the most common UI patterns in web development. You see them in property listing apps, SaaS analytics dashboards, e-commerce product pages, and admin panels.

But building a card that handles hover states cleanly, supports dark mode, stays accessible, and works across screen sizes takes more than wrapping content in a

. You need a consistent component structure, a reliable design system, and well-thought-out Tailwind patterns.

In this tutorial, you'll build four types of production-ready card components using shadcn/ui and Base UI primitives via Shadcn Space. Each card targets a specific, real-world UI pattern that developers run into regularly.

By the end, you'll have:

A Preview Card with a group hover image effect, an overlay arrow icon, and a property details layout
An Analytics Card with typed metric props, conditional badge colors, and a decorative background image
A Statistics Card with a responsive four-column e-commerce stats grid and icon badges
An Ecommerce Product Variant Card with size selection, a wishlist toggle, a bag button, and a ripple animation on the buy button

Prerequisites
Why shadcn/ui?
What is Shadcn Space?
What You'll Build
How to Set Up the CLI Registry
How to Build the Preview Card (card-02)
Live Preview
How to Build the Analytics Card (card-05)
Live Preview
How to Build the Statistics Card (card-06)
Live Preview
How to Build the Ecommerce Product Variant Card (card-17)
Live Preview
Quick Reference Table
Key Concepts Recap
Conclusion
Resources

Prerequisites

Before you start, make sure you have the following in place:

Node.js 18 or higher installed
A Next.js or React project set up
shadcn/ui initialized in your project (npx shadcn@latest init)
Tailwind CSS configured
Basic knowledge of React and TypeScript

If you haven't initialized shadcn/ui yet, run npx shadcn@latest init in your project root and follow the prompts before continuing.

Why shadcn/ui?

shadcn/ui is a collection of accessible, open-source React components built on top of Radix UI, Base UI, and styled with Tailwind CSS.

The way it works is different from a traditional component library. Instead of installing a package, you use a CLI to copy the component source files directly into your project. This means you own every line of the code. You can read it, edit it, and the component will never break because of a library update you didn't control.

Some key benefits:

Accessible by default: built on Radix UI and Base UI primitives
Fully Tailwind-based: no external CSS files, no specificity conflicts
Zero lock-in: components live in your components/ folder, not inside node_modules
Works everywhere: Next.js, Vite, Astro, Remix, and other React frameworks

The Card, Badge, Button, and Separator components you'll use in this tutorial all come from the shadcn/ui base install.

What is Shadcn Space?

Shadcn Space is an open-source registry of production-ready components and UI blocks built on top of shadcn/ui. It extends the default shadcn/ui component set with additional variants from common patterns to highly appealing layouts.

The key difference from the default shadcn/ui Card component is that Shadcn Space cards are designed for specific layout patterns. You get more structure out of the box.

Each component in Shadcn Space supports both Radix UI and Base UI primitives. You also get the functionality of Copy Prompt. This tutorial uses the Base UI versions. You install them the same way as any shadcn/ui component, through a single CLI command, and the source files land in your project.

You can browse the full card collection in the Shadcn card component library.

What You'll Build

Here's an overview of the four cards you'll build, along with their specific features:

Preview Card (card-02)

Large image with hover brightness and scale animation
An arrow icon that appears only on hover
Property title and location
Price badge with a teal color scheme
Amenity row with bed, bath, and area icons

Analytics Card (card-05)

Typed TypeScript props with a built-in default dataset
Two metric columns separated by a vertical divider
Conditional badge colors based on positive or negative trend
Decorative background image pinned to the bottom-right corner

Statistics Card (card-06)

Four-column responsive grid that stacks on mobile
Iconify Solar icon set for each metric
Badge with trend direction icon
Border dividers are removed from the last column automatically

Ecommerce Product Variant Card (card-17)

Product image with 3D drop shadow and hover zoom
Wishlist heart toggle with dark mode support
Size selector with active state highlighting
Bag icon toggle that fills on click
"Buy Now" button with a CSS ripple animation
Dynamic delivery date with ordinal suffix formatting

How to Set Up the CLI Registry

Before you run any install commands, you need to register the Shadcn Space registry in your components.json file.

Open components.json in your project root and add the registries field:

{
  "registries": {
    "@shadcn-space": {
      "url": "https://shadcnspace.com/r/{name}.json"
    }
  }
}

This tells the shadcn CLI where to find components prefixed with @shadcn-space/. Without this step, all the install commands in this tutorial will fail.

Your full components.json should look something like this after adding the registry:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "default",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  },
  "registries": {
    "@shadcn-space": {
      "url": "https://shadcnspace.com/r/{name}.json"
    }
  }
}

For a full walkthrough of how the CLI works with third-party registries, visit the getting started guide. You can also watch the video walkthrough if you prefer to follow along visually.

How to Build the Preview Card (card-02)

What the Preview Card Does

The Preview Card is designed for property listings, hotel pages, or any content that benefits from a large image with supporting details below it.

When a user hovers the card, the image darkens and scales up. An arrow icon appears in the corner. Below the image, a title, location, price badge, and amenity row are displayed.

How to Install the Preview Card

Run one of the following commands based on your package manager:

npm:

npx shadcn@latest add @shadcn-space/card-02

pnpm:

pnpm dlx shadcn@latest add @shadcn-space/card-02

Yarn:

yarn dlx shadcn@latest add @shadcn-space/card-02

Bun:

bunx --bun shadcn@latest add @shadcn-space/card-02

The CLI copies the component into your project at:

components/
  shadcn-space/
    card/
      Card-02.tsx

The Component Code

import { Badge } from "@/components/ui/badge";
import { Card } from "@/components/ui/card";
import { ArrowRight, Bath, BedDouble, Expand } from "lucide-react";

const PreviewCard = () => (
  
    
      
        
          
        
      

      
        
      
    

    
      
        
          
            
              Serenity Residential Home
            
          
          
            15 S Aurora Ave, Miami
          
        

        
          $570,000
        
      

      
        
          
          5 Bedrooms
        

        
          
          3 Bathrooms
        

        
          
          
            120m²
          
        
      
    
  
);

export default PreviewCard;

Let's now go through how this code works.

1. Group hover behavior

The group class on the outer Card element is the core of this component. Any child element with a group-hover: class will respond when the card is hovered, not just that individual element.

This is how the image darkens (group-hover:brightness-50), scales up (group-hover:scale-125), and the arrow icon appears (group-hover:block).

2. Overflow clipping on image zoom

Without overflow-hidden on the image wrapper, the scale-125 transform would bleed past the card's rounded corners on hover. The wrapper clips the image so it stays inside the card boundary.

Notice that rounded-t-2xl appears on both the wrapper and the image itself to maintain a consistent corner radius during the transition.

3. Logical border properties in the amenity row

The amenity row uses border-e instead of border-r. This is a CSS logical property meaning "border at the inline end." In left-to-right layouts, that's the right side. In right-to-left layouts, it flips automatically. Using logical properties is a good production habit for any component that may need to support multiple locales.

Live Preview:

How to Build the Analytics Card (card-05)

What the Analytics Card Does

The Analytics Card is a compact dashboard widget. It shows two metrics side by side with values and percentage-change badges. A decorative chart image sits in the bottom-right corner.

The component is typed with TypeScript interfaces, making it easy to swap in real data from an API.

How to Install the Analytics Card

npx shadcn@latest add @shadcn-space/card-05

The CLI copies the component into:

components/
  shadcn-space/
    card/
      card-05.tsx

The Component Code

import { Badge } from "@/components/ui/badge";
import { Card, CardContent } from "@/components/ui/card";
import { Separator } from "@/components/ui/separator";
import { cn } from "@/lib/utils";

type DashboardMetric = {
  label: string;
  value: string;
  percentage: string;
  isPositive?: boolean;
};

type MainDashboardData = {
  title: string;
  description: string;
  metrics: DashboardMetric[];
};

type WidgetProps = {
  mainDashboard?: MainDashboardData;
};

const mainDashboardData: MainDashboardData = {
  title: "Analytics Dashboard",
  description: "Check all the statistics",
  metrics: [
    {
      label: "Earnings",
      value: "$27,850",
      percentage: "+18%",
      isPositive: true,
    },
    {
      label: "Expense",
      value: "$18,453",
      percentage: "-5%",
      isPositive: false,
    },
  ],
};

const AnalyticsCard = ({ mainDashboard = mainDashboardData }: WidgetProps) => {
  return (
    
      
        
          
            
              
                
                  {mainDashboard.title}
                
                
                  {mainDashboard.description}
                
              
              
                {mainDashboard.metrics.map((metric, index) => (
                  
                    
                      
                        {metric.label}
                      
                      
                        
                          {metric.value}
                        
                        
                          {metric.percentage}
                        
                      
                    
                    {index < mainDashboard.metrics.length - 1 && (
                      
                    )}
                  
                ))}
              
            

            
          
        
      
    
  );
};

export default AnalyticsCard;

How the Analytics Card works:

1. Optional props with a default dataset

The component accepts an optional mainDashboard prop. If you don't pass anything, it falls back to mainDashboardData, the constant is defined in the same file:

const AnalyticsCard = ({ mainDashboard = mainDashboardData }: WidgetProps) => {

This pattern lets the component work out of the box in demos or Storybook, while still being fully driven by real API data in production. To connect it to live data, you just pass a prop that matches the MainDashboardData shape.

2. Conditional badge colors with `cn()`

The cn() utility (from @/lib/utils) merges Tailwind class names and handles conditional logic cleanly. It also de-duplicates conflicting Tailwind classes automatically, which plain template literals don't do:

className={cn(
  "font-normal text-muted-foreground",
  metric.isPositive ? "bg-teal-400/10" : "bg-red-500/10"
)}

3. Separators only between metrics, not after the last one

The Separator component renders only between metrics, never after the last one. The index check handles this:

{index < mainDashboard.metrics.length - 1 && (
  
)}

4. Absolute-positioned decorative image

The chart image is used absolute bottom-0 right-0 to pin it to the card's bottom-right corner. It hides on small screens with hidden sm:block to avoid layout issues on mobile. The parent Card has relative positioning to contain it.

Live Preview:

How to Build the Statistics Card (card-06)

What the Statistics Card Does

The Statistics Card displays four e-commerce metrics in a horizontal grid: Orders, Sales, Profit, and Expense. Each column has an icon, a large value, a time period label, and a badge showing the percentage trend.

The layout is fully responsive, collapsing from four columns to two on medium screens and stacking on mobile.

This card uses @iconify/react for icons instead of lucide-react, giving you access to thousands of icon sets using string-based icon names.

How to Install the Statistics Card

First, install @iconify/react if you don't have it:

npm install @iconify/react

Then add the card component:

npx shadcn@latest add @shadcn-space/card-06

The CLI copies the component into:

components/
  shadcn-space/
    card/
      card-06.tsx

The Component Code

"use client";
import { Icon } from "@iconify/react";
import { Card, CardContent } from "@/components/ui/card";
import { Badge } from "@/components/ui/badge";

const StatisticsCard = () => {
  const EcommerceActions = [
    {
      title: "Orders",
      subtitle: "5868",
      cardIcon: "solar:bag-4-line-duotone",
      badgeColor: "bg-teal-400/10",
      statusValue: "+18%",
      statusIcon: "solar:course-up-line-duotone",
    },
    {
      title: "Sales",
      subtitle: "$96,850",
      cardIcon: "solar:box-line-duotone",
      badgeColor: "bg-orange-400/10",
      statusValue: "-5%",
      statusIcon: "solar:course-down-line-duotone",
    },
    {
      title: "Profit",
      subtitle: "$82,906",
      cardIcon: "solar:chart-square-line-duotone",
      badgeColor: "bg-teal-400/10",
      statusValue: "+18%",
      statusIcon: "solar:course-up-line-duotone",
    },
    {
      title: "Expense",
      subtitle: "$14,653",
      cardIcon: "solar:star-line-duotone",
      badgeColor: "bg-teal-400/10",
      statusValue: "+18%",
      statusIcon: "solar:course-up-line-duotone",
    },
  ];

  return (
    
      
        
          {EcommerceActions.map((item, index) => (
            
              
                
                  
                    {item.title}
                    
                      
                    
                  
                  
                    {item.subtitle}
                    
                      Last 7 days
                      
                        
                          {item.statusValue}
                          
                        
                      
                    
                  
                
              
            
          ))}
        
      
    
  );
};

export default StatisticsCard;

How the Statistics Card works:

1. Data-driven layout with an array

All four metrics live in the EcommerceActions array. Adding or removing a metric only requires updating the array. The JSX stays the same. This is the right approach for any component with a repeating structure: keep data and markup separate.

2. Responsive column widths

Each column uses three width classes to handle every breakpoint:

w-full on mobile (single column, stacked vertically)
md:w-6/12 on medium screens (two columns)
lg:w-3/12 on large screens (four equal columns)

The flex-wrap on the CardContent lets columns wrap naturally on smaller screens. lg:flex-nowrap forces them into a single row on large screens.

3. Removing the last border with `last:`

The last:border-e-0 class removes the right border from the final column. Without it, there'd be a stray border on the right edge of the card.

The last: variant is a Tailwind pseudo-class that targets the last child element in a group, which is cleaner than tracking the index manually.

4. Why `"use client"` is needed here

The @iconify/react package requires a browser environment. In Next.js with the App Router, any component that imports a client-only package needs the "use client" directive at the top of the file. Without it, the server will throw an error during rendering.

Live Preview:

How to Build the Ecommerce Product Variant Card (card-17)

What the Ecommerce Product Variant Card Does

This is the most interactive card in this tutorial. It's a product card for a shoe listing with a hover zoom, a wishlist toggle, size buttons, a bag toggle, and a ripple-animation buy button. All interactions are handled with React's useState, so no external state management library is required.

How to Install the Product Variant Card

npx shadcn@latest add @shadcn-space/card-17

The CLI copies the component into:

components/
  shadcn-space/
    card/
      card-17.tsx

The Component Code

"use client";

import { useState } from "react";
import { Card, CardContent, CardFooter } from "@/components/ui/card";
import { Button } from "@/components/ui/button";
import { Heart, ShoppingBag } from "lucide-react";
import { cn } from "@/lib/utils";

const sizes = ["7", "8", "9", "10"];

const getDeliveryDate = () => {
  const date = new Date();
  date.setDate(date.getDate() + 3);
  const day = date.getDate();
  const month = [
    "Jan", "Feb", "Mar", "Apr", "May", "Jun",
    "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
  ][date.getMonth()];
  const suffix = ["th", "st", "nd", "rd"][
    day % 10 > 3 ? 0 : (day % 100 - day % 10 !== 10 ? day % 10 : 0)
  ];
  return `${day}${suffix} ${month}`;
};

export default function EcommerceProductCard() {
  const [activeSize, setActiveSize] = useState(1);
  const [isWishlisted, setIsWishlisted] = useState(false);
  const [inBag, setInBag] = useState(false);

  return (
    
      

        {/* Image zone */}
        
          

          {/* Discount badge */}
          
            -21%
          

          {/* Wishlist button */}
          
        

        {/* Info zone */}
        
          
            Nike
            
              Air Max Pulse Running Shoes
            
          

          
            
              Down 21%
            
            $150
            $119
          

          
            Delivery by{" "}
            
              {getDeliveryDate()}
            
          

          {/* Size selector */}
          
            {sizes.map((s, i) => (
              
            ))}
          
        

        {/* Action zone */}
        
          

          
        

      
    
  );
}

How the Ecommerce Product Variant Card works:

1. Named group hover scopes

This card uses two independent hover group scopes: group/card on the outer card and group/btn on the Buy Now button. Tailwind's named group feature uses the /name suffix to keep them separate:

// Card-level hover: zooms the product image

  

// Button-level hover: triggers the ripple animation

Without named groups, hovering the button would also trigger the card's hover styles. The /card and /btn suffixes prevent this.

2. CSS ripple animation on the Buy Now button

The ripple effect uses a pure CSS scale animation. A white circle (w-8 h-8 rounded-full) starts at scale-0 and transitions to scale-[20] when the button is hovered. The overflow-hidden on the Button clips it to the button's boundary. The z-10 on the label keeps the text visible above the expanding circle.

3. Ordinal suffix logic for the delivery date

The getDeliveryDate() function calculates a date three days from now and attaches the correct ordinal suffix (st, nd, rd, th):

const suffix = ["th", "st", "nd", "rd"][
  day % 10 > 3 ? 0 : (day % 100 - day % 10 !== 10 ? day % 10 : 0)
];

The logic handles the edge cases for 11th, 12th, and 13th, which always use "th" regardless of their last digit. This is a common gotcha in ordinal formatting.

4. `suppressHydrationWarning` on the delivery date span

The delivery date is calculated at render time using new Date(). The server calculates it at request time, and the client recalculates it at hydration time.

If there's a timezone difference, React throws a hydration mismatch warning. suppressHydrationWarning silences this warning for that specific node without affecting the rest of the tree.

Live Preview:

Quick Reference Table

Card	Identifier	Use Case
Preview Card	`card-02`	Property listings, hotel cards, product previews
Analytics Card	`card-05`	Dashboard widgets with metric data
Statistics Card	`card-06`	E-commerce stats grids
Product Variant Card	`card-17`	Product pages with size selection and cart

To install any of these, replace the identifier in the CLI command:

npx shadcn@latest add @shadcn-space/

Key Concepts Recap

Here's a summary of the key Tailwind, React, and TypeScript patterns used across the four cards in this tutorial.

Tailwind Group Hover

The group class on a parent element lets any child respond to the parent's hover state using group-hover: classes.

For nested hover scopes, use named groups like group/card and group/btn with group-hover/card: and group-hover/btn:. This prevents hover styles from bleeding across component boundaries.

The `cn()` Utility

cn() from @/lib/utils merges Tailwind class strings, handles conditional class logic, and de-duplicates conflicting Tailwind utilities. Use it instead of template literals whenever you have conditional classes.

`last:` Tailwind Variant

The last: pseudo-class variant targets the last child element in a group. In the Statistics Card, last:border-e-0 remove the trailing border from the final column without any index tracking in JavaScript.

CSS Logical Properties

border-e means "border at the inline end," which is the right side in LTR layouts and the left side in RTL layouts. Using logical properties like border-e, ps-, and pe- instead of border-r, pl-, and pr- makes your components locale-aware by default.

TypeScript Optional Props with Defaults

Assigning a default value directly in the function signature, like ({ mainDashboard = mainDashboardData }: WidgetProps), is a clean pattern for components that need sensible fallback data while still being configurable. It works for demos, Storybook, and production use with real API data.

`"use client"` in Next.js App Router

Any component that uses useState, browser APIs, or client-only packages like @iconify/react needs the "use client" directive at the top of the file. Without it, the Next.js App Router will try to render the component on the server and throw an error.

`suppressHydrationWarning`

When a value rendered on the server (for example, the current date or time) differs from the value rendered on the client due to timezone differences, React throws a hydration mismatch warning. Adding suppressHydrationWarning to the specific element silences the warning without affecting the rest of the component tree.

CSS Ripple Animation Pattern

A CSS ripple effect can be built without JavaScript by using a scale-0 to scale-[N] transition on a rounded-full element placed inside an overflow-hidden container. On hover, the circle expands and gets clipped by the container boundary. The label text sits above it with relative z-10.

Conclusion

In this tutorial, you built four production-ready card components using shadcn/ui and Base UI primitives:

Preview Card: group hover image animation, overflow clipping, and a logical border amenity row
Analytics Card: typed props with default data, conditional badge colors with cn(), and an absolutely-positioned decorative image
Statistics Card: data-driven repeating layout, responsive flex columns, and automatic last-border removal with last:
Ecommerce Product Variant Card: named hover groups, a CSS ripple button, ordinal date formatting, and hydration warning suppression

Each card is installed with one CLI command and lives in your project's source tree. You own the code and can modify anything to fit your design system.

The patterns covered here, from named group hover scopes to typed props with defaults to logical CSS properties, apply well beyond card components. You'll find them useful across most UI components you build with shadcn/ui and Tailwind CSS.

Resources

Shadcn UI: Component library and documentation home
Shadcn Card Component Collection: All card variants available in Radix and Base UI
How to Use the Shadcn CLI: Getting started guide for the CLI and registry setup
Shadcn CLI Reference: Full CLI command reference
Component Getting Started Guide: How to install and use individual components
Shadcn Components: Full component library with all available categories
Shadcn Dashboard UI Blocks: Ready-to-use dashboard layout blocks built from the same system
Official Shadcn/ui Documentation
Shadcn Figma Kit: Figma UI kit that mirrors the Shadcn Space component system
Video Walkthrough: How to Use Shadcn Space with CLI: YouTube tutorial for CLI setup and component installation
@iconify/react on npm: Icon library used in the Statistics Card

How to Build an Animated Badge Component with shadcn/ui

Vaibhav Gupta — Wed, 24 Jun 2026 17:00:48 +0000

Badges are everywhere in modern web apps. You see them on notification counters, status labels, and feature tags.

Most of them are static, though. They sit there doing nothing, blending into the page. But a well-animated badge can tell the user something happened without them having to read a single word.

In this tutorial, you'll build an animated “success” badge using shadcn/ui, Tailwind CSS, and Framer Motion. The badge will have a glowing top light, an animated check icon that bounces into view, and letters that drop in one at a time with a stagger effect.

The component comes from the Shadcn Space badge collection and uses the Base UI primitive version of Badge. You'll install it with a single CLI command, then walk through every piece of code.

By the end, you'll build an animated "Success" badge by:

Installing the badge-07 component from Shadcn Space using the Shadcn CLI
Using motion.create() to wrap the shadcn/ui Badge into an animatable component
Adding layered radial-gradient glow effects as absolutely positioned spans
Animating the check icon with a scale and rotate entrance
Animating each letter of the label individually using staggered variants

Prerequisites
What You'll Build
How to Install the Component
Component Structure
Step 1: Set Up the Imports
Step 2: Define Letter Animation Variants
Step 3: Wrap the Badge with Motion
Step 4: Build the Glow Layers
Step 5: Animate the Icon
Step 6: Animate Each Letter
How to Use It in Your App
How to Customize the Component
Live Preview
Key Concepts Recap
Conclusion
Resources

Prerequisites

You'll need:

A Next.js project with shadcn/ui initialized
Tailwind CSS set up
motion installed: npm install motion
lucide-react installed: npm install lucide-react
Basic TypeScript and React knowledge

What You'll Build

In this tutorial, we'll build a self-contained animated badge with three moving parts:

├── MotionBadge (outline, rounded-full, teal border)
│   ├── Glow layers  → 3 radial gradient spans above the top border
│   ├── CheckCircle  → scale + rotate entrance, easeOutBack
│   └── Letter spans → staggered drop-in, easeOutCubic

After installation, the component file lands here:

components/
└── shadcn-space/
    └── badge/
        └── badge-07.tsx

How to Install the Component

Shadcn UI provides a registry of production-ready components. You pull them into your project with the Shadcn CLI, just like you'd add any standard shadcn/ui component.

Before running any command, check the Getting Started guide or the CLI page for setup details.

You can also follow along with this video walkthrough:

Run the command for your package manager:

pnpm

pnpm dlx shadcn@latest add @shadcn-space/badge-07

npm

npx shadcn@latest add @shadcn-space/badge-07

Yarn

yarn dlx shadcn@latest add @shadcn-space/badge-07

Bun

bunx --bun shadcn@latest add @shadcn-space/badge-07

Note: badge-07 uses the Base UI primitive version of Badge. Both Radix and Base UI versions are available in the registry. This tutorial covers the Base UI version.

Component Structure

Here's the complete component. Read through it once, then each step below breaks down a specific part.

'use client'
import { motion, type Variants } from "motion/react";
import { CheckCircle } from "lucide-react";
import { Badge } from "@/components/ui/badge";
import { cn } from "@/lib/utils";

const LETTER_VARIANTS: Variants = {
  hidden: { y: -14, opacity: 0 },
  visible: (i: number) => ({
    y: 0,
    opacity: 1,
    transition: {
      delay: i * 0.038,
      duration: 0.35,
      ease: [0.215, 0.61, 0.355, 1],
    },
  }),
};

const MotionBadge = motion.create(Badge);

const SuccessBadgeDemo = () => {
  const label = "Success";

  return (
    
      {/* Top glow */}
      
      
      

      {/* Icon */}
      
        
      

      {/* Animated label */}
      
        {label.split("").map((char, i) => (
          
            {char}
          
        ))}
      
    
  );
};

export default SuccessBadgeDemo;

Now let's break it down piece by piece.

Step 1: Set Up the Imports

'use client'
import { motion, type Variants } from "motion/react";
import { CheckCircle } from "lucide-react";
import { Badge } from "@/components/ui/badge";
import { cn } from "@/lib/utils";

'use client' marks this as a Client Component in Next.js App Router. Motion animations run in the browser, not on the server, so this directive is required.

motion/react is the import path for Motion v11 and above. If your project uses an older version, the import is framer-motion. The Variants type is a TypeScript helper for typing named animation state objects.

cn() is the class name utility that ships with every shadcn/ui project. It merges Tailwind classes and handles conditional logic cleanly.

Step 2: Define Letter Animation Variants

const LETTER_VARIANTS: Variants = {
  hidden: { y: -14, opacity: 0 },
  visible: (i: number) => ({
    y: 0,
    opacity: 1,
    transition: {
      delay: i * 0.038,
      duration: 0.35,
      ease: [0.215, 0.61, 0.355, 1],
    },
  }),
};

Each letter starts 14px above its final position and is fully transparent. When the component mounts, it moves to y: 0 at full opacity.

The delay: i * 0.038 formula is the stagger. Letter 0 has no delay, letter 1 waits 38ms, letter 2 waits 76ms, and so on. This makes the letters appear to cascade in from left to right.

The ease value [0.215, 0.61, 0.355, 1] is easeOutCubic. It starts fast and decelerates at the end, giving each letter a natural landing rather than a hard stop.

The visible function accepts a custom value. When you pass custom={i} on the motion.span, Motion calls this function with that index. Each letter calculates its own delay independently.

Accessibility tip: To respect users with reduced motion preferences, import useReducedMotion from motion/react and skip the stagger when it returns true.

Step 3: Wrap the Badge with Motion

const MotionBadge = motion.create(Badge);

The Badge Component from shadcn/ui is a standard React component. You can't apply Motion props like animate or initial to it directly.

motion.create() wraps any React component and returns a new version that accepts all Motion animation props. The result, MotionBadge, behaves exactly like Badge But it's now fully animatable.

Use this pattern any time you want to animate a custom or third-party library component with Motion.

Step 4: Build the Glow Layers

Three spans stack on top of each other above the badge border. Each is narrower and more opaque than the one behind it:

Layer	Position	Width	Blur	Final Opacity
Outer	`-top-2`	80%	`blur`	0.55
Middle	`-top-1`	56%	`blur-sm`	0.75
Inner line	`top-0`	44%	none	0.90

The innermost layer is only 1px tall (h-px) with no blur. This gives the glow a crisp, bright edge right at the badge border. The two outer layers create the soft falloff around it.

All three carry aria-hidden because they're purely decorative. Screen readers skip them. The overflow-visible class on MotionBadge is what allows these spans to render outside the component's boundary without clipping.

Step 5: Animate the Icon

The icon starts at 35% scale, invisible, and rotated 25 degrees counter-clockwise. It animates to full size and zero rotation on mount.

The ease value [0.175, 0.885, 0.32, 1.275] is easeOutBack. Unlike easeOutCubic, this curve overshoots its target slightly before snapping back. The icon appears to spring into place. It is a subtle effect, but it makes the icon feel physical.

shrink-0 on the wrapper prevents the icon from compressing inside the flex container.

Step 6: Animate Each Letter


  {label.split("").map((char, i) => (
    
      {char}
    
  ))}

label.split("") turns "Success" into ["S", "u", "c", "c", "e", "s", "s"]. Each character gets its own motion.span.

variants={LETTER_VARIANTS} connects each span to the animation states from Step 2. custom={i} passes the character's index into the visible resolver so each letter knows its own delay.

Two Tailwind classes matter here:

overflow-hidden on the wrapper clips, each letter as it slides in from above. Without it, letters would be visible outside the badge before they land.
inline-block on each motion.span is required for translateY to work. CSS transforms do not apply to inline elements by default.

How to Use It in Your App

Import and render SuccessBadgeDemo anywhere in your project:

// app/page.tsx
import SuccessBadgeDemo from "@/components/shadcn-space/badge/badge-07";

export default function Page() {
  return (
    
      
    
  );
}

The component is self-contained. It carries its own animation state, theme tokens, and glow layers. No props are required.

How to Customize the Component

You can change the label by replacing "Success" it with any string. The letter animation applies automatically since it splits whatever string you pass.

To build a complete blue "Verified" variant, you just need to change three things: the border color class, the glow gradient color values, and the icon. Here's the full updated component:

'use client'
import { motion, type Variants } from "motion/react";
import { ShieldCheck } from "lucide-react";
import { Badge } from "@/components/ui/badge";
import { cn } from "@/lib/utils";

const LETTER_VARIANTS: Variants = {
  hidden: { y: -14, opacity: 0 },
  visible: (i: number) => ({
    y: 0,
    opacity: 1,
    transition: {
      delay: i * 0.038,
      duration: 0.35,
      ease: [0.215, 0.61, 0.355, 1],
    },
  }),
};

const MotionBadge = motion.create(Badge);

const VerifiedBadgeDemo = () => {
  const label = "Verified";

  return (
    
      
      
      

      
        
      

      
        {label.split("").map((char, i) => (
          
            {char}
          
        ))}
      
    
  );
};

export default VerifiedBadgeDemo;

The only changes from the original: border-blue-400/25 on the badge, rgba(96, 165, 250, ...) in the glow gradients (blue-400 in Tailwind), ShieldCheck for the icon, and text-blue-400 on the icon class.

To adjust stagger speed, just change the delay multiplier in LETTER_VARIANTS:

delay: i * 0.06, // slower stagger
delay: i * 0.02, // faster stagger

You can also explore the Shadcn Blocks collection to see how animated badges fit into full dashboard and card layouts.

Live Preview

Key Concepts Recap

Concept	What It Does
`motion.create(Component)`	Wraps any React component to accept Motion animation props
`Variants`	Named animation states (`hidden`, `visible`) defined outside JSX for reuse
`custom={i}` + variant function	Passes a per-element value into the variant resolver for dynamic transitions
`delay: i * 0.038`	Stagger formula: each element's delay grows by its index
`easeOutCubic` `[0.215, 0.61, 0.355, 1]`	Fast start, smooth deceleration. Letter drop-in.
`easeOutBack` `[0.175, 0.885, 0.32, 1.275]`	Overshoots slightly, snaps back. Icon pop.
Three stacked radial gradients	Wide + soft outer glow, narrow + sharp inner line
`overflow-visible` on the badge	Allows glow spans to extend outside the component's own bounds

Conclusion

In this tutorial, you built a complete animated badge from scratch with a layered glow, bouncing icon, and staggered letter animation. Every part of it uses your existing Shadcn theme tokens, so it drops into any project without extra configuration.

You can browse more Shadcn Components on Shadcn Space to apply the same animation patterns to other UI elements. If you work with external services and tooling in your stack, the Shadcn MCP integration is worth looking at as a next step.

Resources

Shadcn Space Badge Components: with all badge variants, including Pending, Failed, and more
Shadcn Space Getting Started Guide: how to use the Shadcn CLI with third-party registries
Motion Docs: official documentation for motion/react
Lucide React: icon library used in this tutorial
Shadcn/ui Documentation
YouTube: Shadcn Space CLI Walkthrough

How to Build an Admin Dashboard Sidebar with shadcn/ui and Base UI

Vaibhav Gupta — Tue, 14 Apr 2026 16:25:08 +0000

Admin dashboards are one of the most common real-world UI components you will build as a React developer. At the heart of nearly every dashboard is a sidebar, a persistent navigation panel that organizes pages, tools, and features into a clean, scannable structure.

Building a sidebar from scratch involves much more than an

element. You need collapsible submenus, active state tracking across parent and child items, accessible keyboard navigation, a scroll area for long nav lists, and a consistent design system that holds together across screen sizes.

In this tutorial, you'll learn how to build a fully functional, accessible admin dashboard sidebar using shadcn/ui, a collection of beautifully designed, accessible React components, and a pre-built community block from Shadcn Space, which extends shadcn/ui with ready-to-use dashboard UI patterns.

By the end of this tutorial, you'll have a working sidebar that includes:

Grouped navigation sections with uppercase labels
Collapsible parent menu items with child links
Active state tracking across both parent and child items
A floating sidebar with an independent scroll area
A promotional card pinned inside the sidebar footer

Prerequisites
What You Will Build
Why shadcn/ui?
What is Shadcn Space?
How to Install the Sidebar Block
How to Understand the Folder Structure
How to Build the Page Layout
How to Build the AppSidebar Component
How to Define the Navigation Data
How to Build the NavMain Component
How to Handle Active States and Collapsible Menus
How to Style the Sidebar
Live Preview
Summary

Prerequisites

Before you start, make sure you have the following:

Node.js 18+ installed on your machine
Basic knowledge of React and TypeScript
Familiarity with Tailwind CSS utility classes
A package manager installed (npm, pnpm, yarn, or bun)

You don't need prior experience with shadcn/ui, but it helps to have read through the official docs at least once.

What You Will Build

In this article, you'll build a fully functional admin dashboard sidebar with the following features:

Floating sidebar shell: a card-style sidebar with rounded corners, a drop shadow, and a configurable width
Grouped navigation: navigation items organized under section labels like Dashboards, Pages, Apps, and Form Elements
Collapsible submenus: parent items like Blogs and Shadcn Forms that expand on click to reveal child links
Active state tracking: visual highlighting of the selected parent and child item at all times
Sidebar toggle: a trigger button in the page header that opens and closes the sidebar
Promotional card: a "Get Premium" card at the bottom of the sidebar scroll area

Why shadcn/ui?

shadcn/ui is a collection of beautifully designed, accessible React components built on top of Radix UI and styled with Tailwind CSS.

Instead of installing a traditional component library as a dependency, you copy components directly into your project using a CLI. This gives you full ownership of the code structure and styling. You can read every line, change anything, and the components never break because of a library update you didn't control.

Some key benefits of shadcn/ui include:

Accessible by default, built on Radix and Base UI primitives
Fully styled with Tailwind CSS utility classes
Zero lock-in: the code lives in your project, not inside node_modules
Works with Next.js, React, Astro, Vite, and other frameworks
A growing ecosystem of community-built blocks and registries

The Sidebar, Collapsible, ScrollArea, Card, and Button Components you'll use in this tutorial all come from shadcn/ui.

What is Shadcn Space?

Shadcn Space is an open-source library of pre-built UI blocks built on top of shadcn/ui. It provides ready-to-use dashboard layouts, sidebars, tables, cards, and other common admin UI patterns so you don't have to assemble them from individual primitives every time.

Each block in Shadcn Space is installable directly into your project using the shadcn CLI. Once installed, the code is yours: you can read it, extend it, and adapt it to your design system without any runtime dependency on Shadcn Space itself.

For this tutorial, you'll use the sidebar-06 block (it’s free to use), which is a floating admin sidebar with grouped navigation, collapsible submenus, and an integrated scroll area.

Shadcn Space also provides a companion Figma UI Kit that matches the design system used in the blocks, which is useful if you do design work alongside development.

You can explore the full block library and the getting-started documentation in the official Shadcn Space docs.

How to Set Up the Project

Start by creating a new Next.js project if you don't already have one:

npx shadcn@latest init --preset b0 --base base --template next

This command:

Creates a Next.js project
Configures Tailwind CSS
Sets up Base UI as the component foundation
Uses Nova style preset
Configures Lucide icons
Uses Inter font
Applies neutral theme tokens

Follow the prompts to configure your base color, CSS variables, and component output directory. This sets up the components/ui directory and the required Tailwind configuration that all shadcn/ui components depend on.

Once the initialization is complete, your components.json project will be created at the root of your project. This file tells the shadcn CLI where to place components, what path aliases you're using, and which styling configuration to follow.

Add this in components.json:

{
  "registries": {
    "@shadcn-space": {
      "url": "https://shadcnspace.com/r/{name}.json",
    }
  }
}

With shadcn/ui initialized, you can now pull in the sidebar-06 block from Shadcn Space. While Shadcn Space provides components for both Radix UI and Base UI, this tutorial uses the Base UI version. Run one of the following commands depending on your package manager:

npm:

npx shadcn@latest add @shadcn-space/sidebar-06

pnpm:

pnpm dlx shadcn@latest add @shadcn-space/sidebar-06

yarn:

yarn dlx shadcn@latest add @shadcn-space/sidebar-06

bun:

bunx --bun shadcn@latest add @shadcn-space/sidebar-06

This command fetches the block from the Shadcn Space registry and scaffolds all the required component files into your project automatically. It also installs any shadcn/ui primitives the block depends on (such as Sidebar, ScrollArea, Card, Button, and Collapsible) if they aren't already present in your components/ui directory.

You can preview the live block and find the installation command on their shadcn sidebar page.

How to Understand the Folder Structure

After installation, your project will contain the following new files:

app/
  sidebar-06/
    page.tsx                  ← Route entry point
assets/
  logo/
    logo.tsx                  ← Logo component
components/
  shadcn-space/
    blocks/
      sidebar-06/
        app-sidebar.tsx       ← Main sidebar shell
        nav-main.tsx          ← Navigation logic and rendering

Each file has a clearly defined responsibility:

app/sidebar-06/page.tsx: the route entry point that wires the sidebar into a page layout using SidebarProvider
assets/logo/logo.tsx: the logo component rendered in the sidebar header
components/shadcn-space/blocks/sidebar-06/app-sidebar.tsx: the main sidebar shell, including the header, scroll area, nav data, and promotional card
components/shadcn-space/blocks/sidebar-06/nav-main.tsx: all navigation rendering logic, including section labels, leaf items, collapsible parents, and active state management

You'll work through each of these files in detail in the sections below.

How to Build the Page Layout

Open app/sidebar-06/page.tsx. This file is the entry point for your dashboard page. It uses SidebarProvider to establish sidebar context across the page, and SidebarTrigger to render a toggle button inside the header.

import { SidebarProvider, SidebarTrigger } from "@/components/ui/sidebar";
import { AppSidebar } from "@/components/shadcn-space/blocks/sidebar-06/app-sidebar";

const Page = () => {
  return (
    
      

      {/* Main content area */}
      
        
          
        
        
      
    
  );
};

export default Page;

Let's break down the key parts of this layout:

SidebarProvider wraps everything on the page. It manages the sidebar's open/closed state and passes it down to child components via React context. Any component that needs to read or change the sidebar state, including SidebarTrigger and AppSidebar, must be a descendant of SidebarProvider.

The --sidebar-width CSS custom property controls the rendered width of the sidebar. It's set inline using a type assertion (as React.CSSProperties) because TypeScript doesn't know about this custom property by default. Setting it here rather than in a CSS file keeps the width configurable on a per-page basis.

SidebarTrigger is a toggle button component that reads the sidebar open/closed state from the nearest SidebarProvider context and flips it on click. It renders in the header so users always have access to the toggle regardless of scroll position.

bg-muted on SidebarProvider creates the light gray outer background that makes the floating sidebar card visually stand out from the page.

How to Build the AppSidebar Component

Open components/shadcn-space/blocks/sidebar-06/app-sidebar.tsx. This component is the main sidebar shell. It composes shadcn/ui's Sidebar, SidebarHeader, and SidebarContent layout primitives and wraps the scrollable navigation area in a ScrollArea component to handle overflow independently.

"use client";

import {
  Sidebar,
  SidebarContent,
  SidebarHeader,
  SidebarMenu,
  SidebarMenuItem,
} from "@/components/ui/sidebar";
import { ScrollArea } from "@/components/ui/scroll-area";
import { Card, CardContent } from "@/components/ui/card";
import { Button } from "@/components/ui/button";
import Logo from "@/assets/logo/logo";
import { NavItem, NavMain } from "@/components/shadcn-space/blocks/sidebar-06/nav-main";
import {
  AlignStartVertical,
  PieChart,
  CircleUserRound,
  ClipboardList,
  Notebook,
  NotepadText,
  Table,
  Languages,
  Ticket,
} from "lucide-react";

The "use client" directive at the top is required because this component uses React state (through NavMain) and event handlers, both of which require the component to run in the browser rather than being server-rendered by Next.js.

Inside app-sidebar.tsxthe navigation structure is defined as a flat array of NavItem objects. Each item belongs to one of three categories:

A section label marked with isSection: true and a label string. Renders as an uppercase group heading.
A leaf item has a title, icon, and href, but no children. Renders as a direct navigation link.
A parent item has a title, icon, and a children array of sub-items. Renders as a collapsible trigger.


export const navData: NavItem[] = [
  // Dashboards Section
  { label: "Dashboards", isSection: true },
  { title: "Analytics", icon: PieChart, href: "#" },
  { title: "CRM Dashboard", icon: ClipboardList, href: "#" },

  // Pages Section
  { label: "Pages", isSection: true },
  { title: "Tables", icon: Table, href: "#" },
  { title: "Forms", icon: ClipboardList, href: "#" },
  { title: "User Profile", icon: CircleUserRound, href: "#" },

  // Apps Section
  { label: "Apps", isSection: true },
  { title: "Notes", icon: Notebook, href: "#" },
  { title: "Tickets", icon: Ticket, href: "#" },
  {
    title: "Blogs",
    icon: Languages,
    children: [
      { title: "Blog Post", href: "#" },
      { title: "Blog Detail", href: "#" },
      { title: "Blog Edit", href: "#" },
      { title: "Blog Create", href: "#" },
      { title: "Manage Blogs", href: "#" },
    ],
  },

  // Form Elements Section
  { label: "Form Elements", isSection: true },
  {
    title: "Shadcn Forms",
    icon: NotepadText,
    children: [
      { title: "Button", href: "#" },
      { title: "Input", href: "#" },
      { title: "Select", href: "#" },
      { title: "Checkbox", href: "#" },
      { title: "Radio", href: "#" },
    ],
  },
  {
    title: "Form layouts",
    icon: AlignStartVertical,
    children: [
      { title: "Forms Horizontal", href: "#" },
      { title: "Forms Vertical", href: "#" },
      { title: "Forms Validation", href: "#" },
      { title: "Forms Examples", href: "#" },
      { title: "Forms Wizard", href: "#" },
    ],
  },
];

This flat array approach is intentionally simple to maintain. You don't need a nested tree structure because the NavMain component handles the rendering logic for each item type by inspecting each item's shape. Adding a new section, item, or submenu is as straightforward as appending a new object to the array.

How to Build the NavMain Component

Open components/shadcn-space/blocks/sidebar-06/nav-main.tsx. This file contains all the navigation rendering logic. Start with the type definition and the top-level NavMain function:

"use client";

import * as React from "react";
import { ChevronRight, LucideIcon } from "lucide-react";
import { cn } from "@/lib/utils";
import {
  Collapsible,
  CollapsibleTrigger,
  CollapsibleContent,
} from "@/components/ui/collapsible";
import {
  SidebarGroup,
  SidebarGroupLabel,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarMenuSub,
  SidebarMenuSubItem,
  SidebarMenuSubButton,
} from "@/components/ui/sidebar";

export type NavItem = {
  label?: string;
  isSection?: boolean;
  title?: string;
  icon?: LucideIcon;
  href?: string;
  children?: NavItem[];
};

export function NavMain({ items }: { items: NavItem[] }) {
  const [activeParent, setActiveParent] = React.useState(
    items.find((i) => !i.isSection)?.title || null
  );
  const [activeChild, setActiveChild] = React.useState(null);

  return (
    <>
      {items.map((item, index) => (
        
      ))}
    
  );
}

activeParent tracks which top-level nav item is currently selected. It initializes to the title of the first non-section item, so the sidebar always has a selection on first render, and you never show the sidebar with nothing highlighted. activeChild tracks which sub-item inside a collapsible menu is selected.

Both state values are passed down as props to each NavMainItem, so every item in the list can read the current selection and trigger updates to it.

How to Handle Active States and Collapsible Menus

The NavMainItem function branches into one of three rendering paths based on the shape of the incoming item.

How to Render Section Labels

if (item.isSection && item.label) {
  return (
    
      
        {item.label}
      
    
  );
}

Section labels use first:pt-0 to remove the top padding from the very first section, so the nav starts flush with the header.

How to Render Collapsible Parent Items

if (hasChildren && item.title) {
  return (
    
      
        
          
             setActiveParent(item.title!)}
                  className={cn(
                    "rounded-md text-sm font-medium px-3 py-2 h-9 transition-colors cursor-pointer",
                    isParentActive ? "bg-primary! text-primary-foreground!" : ""
                  )}
                >
                  {item.icon && }
                  {item.title}
                  
                
              }
            />
            
              
                {item.children!.map((child, index) => (
                  
                ))}
              
            
          
        
      
    
  );
}

A useEffect inside NavMainItem syncs the local isOpen state with activeParent so that when a different parent is activated, the previously open collapsible stays open until the user explicitly closes it:

React.useEffect(() => {
  if (isParentActive) {
    setIsOpen(true);
  }
}, [isParentActive]);

The ChevronRight icon rotates 90 degrees when the submenu is open, using a Tailwind transition class:

How to Render Leaf Items

if (item.title) {
  return (
    
      
        
           {
              setActiveParent(item.title!);
              setActiveChild(null);
            }}
            className={cn(
              "rounded-md text-sm font-medium px-3 py-2 h-9 transition-colors cursor-pointer",
              isParentActive ? "bg-primary! text-primary-foreground!" : ""
            )}
            render={}
          >
            {item.icon && }
            {item.title}
          
        
      
    
  );
}

The render prop on SidebarMenuButton replaces the default button element with an tag. This preserves correct anchor link semantics and accessibility while keeping the button's visual styling. When a leaf item is clicked, activeChild is reset to null since there is no child to track.

How to Render Child Items in a Submenu

The NavMainSubItem function handles sub-items inside a collapsible. When a child is clicked, it sets both activeChild to itself and activeParent to its parent's title so the parent item remains visually highlighted:

if (item.title) {
  return (
    
       {
          setActiveParent(parentTitle || "");
          setActiveChild(item.title!);
        }}
        render={{item.title}}
      />
    
  );
}

The child uses a different active style (bg-muted with text-foreground) compared to the parent (bg-primary with text-primary-foreground). This visual distinction makes it easy to see both which section you are in and which specific page is currently active.

Sub-items also support nesting. If a child item itself has a children array, NavMainSubItem renders another Collapsible with a nested SidebarMenuSub, allowing you to build multi-level navigation trees without any changes to the data structure.

The full AppSidebar render function puts all of the pieces together:

export function AppSidebar() {
  return (
    
      

        {/* Header with Logo */}
        
          
            
              
                
              
            
          
        

        {/* Scrollable Navigation Content */}
        
          
            
              
            

            {/* Promotional Card */}
            
              
                
                  
                  
                    
                      
                        Grab Pro Now
                      
                      
                        Customize your admin
                      
                    
                    
                  
                
              
            
          
        

      
    
  );
}

Let's walk through the key styling decisions:

variant="floating" gives the sidebar a card-like appearance with rounded corners and a subtle drop shadow. It visually lifts the sidebar off the background rather than making it flush with the page edge like a standard sidebar would.

[&_[data-slot=sidebar-inner]]:h-full is an arbitrary Tailwind variant selector that targets shadcn/ui's internal sidebar slot element. Without this, the sidebar inner container doesn't fill the full available height, which breaks the layout. The data-slot attribute is how shadcn/ui identifies internal sub-elements of compound components.

h-[calc(100vh-100px)] on ScrollArea makes the navigation list independently scrollable. The 100px offset accounts for the sidebar header and padding, so the scroll area doesn't overflow the viewport. The rest of the page layout remains static while the nav scrolls.

The bg-secondary card at the bottom of the scroll area is a common admin dashboard pattern, a soft prompt for an upgrade or onboarding action that lives passively in the sidebar without blocking navigation.

For more details on the Sidebar component's API, variants, and configuration options, refer to the official shadcn/ui sidebar docs.

Live Preview

Summary

Congratulations! You have now built a complete, production-ready admin dashboard sidebar using shadcn/ui and a community block from Shadcn Space.

Here is a recap of everything you covered:

Setting up a Next.js project with shadcn/ui initialized and a pre-built sidebar block installed from Shadcn Space
Using SidebarProvider and SidebarTrigger to manage the sidebar open/closed state across a page layout through React context
Defining navigation data as a flat array of typed NavItem objects covering section labels, leaf items, and collapsible parent items
Rendering all three item types from a single navData source in the NavMain and NavMainItem components
Tracking activeParent and activeChild state in a single location and passing them as props so every item can read and update the shared selection state
Using Collapsible with a useEffect sync to keep parent items open when they are active, and animate the chevron icon on expand and collapse
Applying the floating variant, an arbitrary Tailwind slot selector, and ScrollArea with a calculated height to produce a polished, production-appropriate sidebar layout

This pattern scales well beyond what you built here. You can extend NavItem with additional fields like badge counts, permission flags, or external link indicators. You can swap in real href values and connect activeParent and activeChild to your router so the selection always reflects the current URL. You can also add more sections to navData without touching any rendering logic.

For a quick checkout, we have used the Shadcn Space free Shadcn dashboard block in this dashboard shell.

If you want to explore more pre-built admin UI blocks, components, and templates built on top of shadcn/ui, you can browse the full library at Shadcn Space.

Resources

How to Build an Animated Shadcn Tab Component with Shadcn/ui

Vaibhav Gupta — Mon, 30 Mar 2026 14:17:26 +0000

Tab components are everywhere: dashboards, settings panels, product pages. But most implementations are static, lifeless, and forgettable. What if your tabs felt alive, with smooth spring animations, a stacked card effect on hover, and a polished active indicator that glides between buttons?

A basic tab switcher can show and hide content. A better one gives users a clear active state, smooth transitions, and a little bit of motion that makes the interface feel alive. That's the idea behind this component: a reusable animated tab system built in the Shadcn style, with React, Tailwind CSS, and Motion.

In this tutorial, you’ll build exactly that: a fully animated tab component built by Shadcn/ui, Framer Motion, and a ready-to-use registry component from Shadcn Space.

By the end, you’ll have a reusable component with:

A spring-animated active pill indicator
A stacked card effect that fans out on hover
A smooth entrance animation when the active tab changes
Fully theme-aware styling using Shadcn/ui CSS variables

Video walkthrough: If you prefer to follow along visually, watch the full tutorial on YouTube:

Prerequisites
What You’ll Build
Install the Component via Shadcn Space CLI
Understand the Component Structure
Step 1 - Define the Tab Data Types
Step 2 - Build the Tab Data Array
Step 3 - Build the Tabs Component (Tab Bar + State)
Step 4 - Build the FadeInStack Component
Step 5 - Compose the Page Component
Step 6 - Customize the Component
Live Preview
Key Concepts Recap
Conclusion
Resources

Prerequisites

Before you begin, make sure you have a working knowledge of:

React and TypeScript basics
Tailwind CSS utility classes
The basics of Shadcn/ui (component installation and theming)

You’ll also need a Next.js or Vite project with the following already set up:

Shadcn/ui installed and initialized
Framer Motion (also referred to as motion/react) installed

What You’ll Build

Here’s an overview of the component architecture you’ll create in this tutorial:

AnimatedTabMotion (page/demo entry point)
└── Tabs (tab bar + content orchestrator)
├── Tab buttons (with spring-animated active pill)
└── FadeInStack (stacked, animated content panels)

The key behaviors are:

Spring pill animation – A spring pill animation is a UI effect in which the active tab indicator, a rounded, pill-shaped highlight, physically moves from one button to another using a spring physics curve rather than a standard CSS transition. Instead of teleporting or fading, the pill slides between tabs with a subtle bounce at the end, mimicking the momentum of a real physical object.
Stacked card effect – inactive tab panels are rendered behind the active one, scaled down and slightly faded, giving a layered depth illusion.
Fan-out on hover – when the user hovers over the content area, the stacked cards spread out vertically.
Bounce entrance – the top (active) card animates downward and back into place when a new tab is selected.

Install the Component via Shadcn Space CLI

Shadcn Space is a registry of production-ready Shadcn/ui-compatible components. Instead of scaffolding this component from scratch, you can pull it directly into your project using the Shadcn CLI.

Check out their Getting Started guide to learn how to use the Shadcn CLI with third-party registries.

Run one of the following commands, depending on your package manager:

pnpm

pnpm dlx shadcn@latest add @shadcn-space/tabs-01

npm

npx shadcn@latest add @shadcn-space/tabs-01

Yarn

yarn dlx shadcn@latest add @shadcn-space/tabs-01

Bun

bunx --bun shadcn@latest add @shadcn-space/tabs-01

This scaffolds the component file into your project, pre-wired to your existing Shadcn/ui theme tokens. You can then customize or extend it as needed, which is exactly what you’ll learn in this tutorial.

Understand the Component Structure

Before writing any code, let’s review the full component and break it into logical pieces. Here is the complete implementation:

"use client";

import { useState } from "react";
import { motion } from "motion/react";
import { cn } from "@/lib/utils";

type Tab = {
  title: string;
  value: string;
  content?: React.ReactNode;
};

type TabsProps = {
  tabs: Tab[];
    containerClassName?: string;
  activeTabClassName?: string;
  tabClassName?: string;
  contentClassName?: string;
};

const tabs = [
  {
    title: "Product",
    value: "product",
    content: (
      
        Product Tab
      
    ),
  },
  {title: "Services",
    value: "services",
    content: (
      
        Services tab
      
    ),
  },
  {
    title: "Playground",
    value: "playground",
    content: (
      
        Playground tab
      
    ),
  },
 {
    title: "Content",
    value: "content",
    content: (
      
        Content tab
      
    ),
  },
  {
    title: "Random",
    value: "random",
    content: (
      
        Random tab
      
    ),
  },
];

const Tabs = ({
  tabs,
  containerClassName,
  activeTabClassName,
  tabClassName,
  contentClassName,
}: TabsProps) => {
  const [activeIdx, setActiveIdx] = useState(0);
  const [hovering, setHovering] = useState(false);

  const handleSelect = (idx: number) => {
    setActiveIdx(idx);
  };
const reorderedTabs = [
    tabs[activeIdx],
    ...tabs.filter((_, i) => i !== activeIdx),
  ];

  return (
    <>
      
        {tabs.map((tab, idx) => {
          const isActive = idx === activeIdx;
          return (
            
          );
        })}
      
      
    
  );
};

type FadeInStackProps = {
  className?: string;
  tabs: Tab[];
  hovering?: boolean;
};

const FadeInStack = ({ className, tabs, hovering }: FadeInStackProps) => {
  return (
    
      {tabs.map((tab, idx) => (
        
          {tab.content}
        
      ))}
    
  );
};

export default function AnimatedTabMotion() {
  return (
    <>
      
        
      
    
  );

}

Now, let’s break this down piece by piece.

Step 1: Define the Tab Data Types

type Tab = {
title: string;
value: string;
content?: React.ReactNode;
};
type TabsProps = {
tabs: Tab[];
containerClassName?: string;
activeTabClassName?: string;
tabClassName?: string;
contentClassName?: string;
};

The Tab type defines the shape of each tab item:

title – the label rendered in the tab button.
value – a unique key used to identify each tab (and as the Framer Motion layoutId).
content – an optional React.ReactNode, meaning you can pass any JSX as the panel body.

The TabsProps type makes the Tabs component highly composable. Every visual layer has an override className, so you can restyle the active pill, individual tab buttons, and the content area independently without touching the core logic.

Step 2: Build the Tab Data Array

const tabs = [
{
title: “Product”,
value: “product”,
content: (

Product Tab

), }, // ... more tabs ];

Each tab’s content is a JSX element styled with Shadcn/ui semantic tokens like bg-muted, text-foreground and border-border. This is intentional: these tokens automatically adapt to your light/dark theme without any extra configuration.

You can replace these placeholder

panels with any real content: charts, forms, tables, media, whatever your use case demands.

Step 3: Build the Tabs Component (Tab Bar + State)

const [activeIdx, setActiveIdx] = useState(0);
const [hovering, setHovering] = useState(false);

Two pieces of state drive the entire component:

activeIdx tracks which tab is currently selected (by array index).
hovering tracks whether the user’s cursor is over any tab button, which is passed to FadeInStack to trigger the fan-out effect.

Reorder Tabs for the Stack Effect

const reorderedTabs = [
tabs[activeIdx],
…tabs.filter((_, i) => i !== activeIdx),
];

This is one of the most clever aspects of the architecture. Instead of showing only the active tab’s content, you always render all tab panels – but you put the active one first in the array. This is what enables the stacked-cards visual:

Index 0 = the active panel, rendered on top with full scale and opacity.
Index 1, 2 = the next panels, stacked behind with reduced scale and opacity.
Index 3+ = hidden (opacity 0).

Render the Tab Buttons with a Spring Pill

{tabs.map((tab, idx) => {
const isActive = idx === activeIdx;
return (
   
);
})}

The magic here is layoutId=“clickedbutton” on the motion.div. When only one element with a given layoutId is mounted at a time, Framer Motion tracks its position in the DOM. When it unmounts from one button and mounts onto another, Framer Motion automatically animates the transition is between the two DOM positions. This creates the sliding pill effect with zero manual calculation.

The transition config uses a spring with bounce: 0.3 a duration: 0.6, giving it a natural, slightly elastic feel rather than a mechanical linear slide.

The transformStyle: “preserve-3d” on the button enables 3D CSS transforms, which pair with the [perspective:1000px] on the container for a subtle depth effect.

Step 4: Build the FadeInStack Component

const FadeInStack = ({ className, tabs, hovering }: FadeInStackProps) => {
  return (
    
      {tabs.map((tab, idx) => (
        
          {tab.content}
        
      ))}
    
  );
};

Let’s unpack the visual logic for each motion.div:

`scale: 1 - idx * 0.1`

Each card behind the active one is scaled down by 10% per layer. So:

Active card (idx 0): scale: 1.0
Second card (idx 1): scale: 0.9
Third card (idx 2): scale: 0.8

This creates clear depth separation between the stacked layers.

`top: hovering ? idx * -15 : 0`

When hovering is true, each card shifts upward by idx * 15px. The active card doesn’t move (idx 15 = 0), but the cards behind it fan out at -15px, -30px, and so on. This gives a satisfying “deck spreading” effect on hover.

`zIndex: -idx`

Negative z-index stacks cards in order: the active card sits on top (z-index 0), while subsequent cards descend further behind.

`opacity: idx < 3 ? 1 - idx * 0.1 : 0`

Cards at index 3 and beyond are hidden entirely. The first three cards fade progressively: 1.0, 0.9, 0.8.

`animate={{ y: idx === 0 ? [0, 40, 0] : 0 }}`

Only the active card (idx 0) gets this keyframe animation. When a tab is selected, and the reorderedTabs array is rebuilt, the new active card enters via a downward dip (y: 40) and bounces back to its rest position. This is a quick, tactile confirmation that the tab has changed.

`layoutId={tab.value}`

Each card also has a layoutId matching one value. When reorderedTabs is recomputed, and array positions shift, Framer Motion can track each card’s identity and animate it smoothly between positions, preventing jarring jumps.

Step 5: Compose the Page Component

export default function AnimatedTabMotion() {
  return (
    
      
    
  );
}

The outer wrapper applies [perspective:1000px] – a Tailwind arbitrary property that sets the CSS perspective value. This is what gives the 3D depth to the transformStyle: “preserve-3d” on the tab buttons.

The max-w-5xl and mx-auto center the component on wide screens while items-start left-aligns the tab bar, which matches most real-world UI patterns.

Step 6: Customize the Component

Because Tabs accepts class-name overrides for every visual layer, so you can fully restyle the component to match your design system. Here’s an example with a darker active pill and a tighter layout:

You can also replace the placeholder content panels with real content. Here’s an example using a card with a real description:

const tabs = [
  {
    title: "Overview",
    value: "overview",
    content: (
      
        Product Overview
        
          Our platform helps teams ship faster with a fully integrated design-to-code workflow.
        
      
    ),
  },
  // ...
];

Live Preview

Key Concepts Recap

Here’s a summary of the core Framer Motion techniques used in this component:

Technique	What it does
`layoutId` on `motion.div`	Animates a shared element between DOM positions (the sliding pill)
`layoutId` on `motion.div` per tab	Tracks card identity during re-ordering, so Framer Motion animates position changes
`animate={{ y: [0, 40, 0] }}`	Keyframe animation for the bounce entrance on tab change
`style={{ scale, top, zIndex, opacity }}`	Inline reactive styles that create the stacked-card depth effect
`transition={{ type: "spring" }}`	Applies a physics-based spring curve instead of a CSS easing function

Conclusion

In this tutorial, you built a fully animated, theme-aware tab component using Shadcn/ui and Framer Motion. You learned how to:

Use layoutId to create a spring-animated sliding pill indicator
Render all tab panels simultaneously and reorder them to create a stacked card effect
Drive hover and depth effects with inline reactive style props
Apply Framer Motion keyframe animations for a tactile bounce entrance
Keep the component fully customizable via class name overrides

This pattern, combining Shadcn/ui’s semantic design tokens with Framer Motion’s layout animations, scales well beyond tabs. You can apply the same layoutId and stack reorder technique to carousels, image galleries, notification toasts, and more.

You can explore the full component and more animated UI blocks at Shadcn Space, where the CLI command makes it trivial to drop production-quality components directly into your project.

Resources

I wrote this article with the help of Mihir Koshti (Sr. Full Stack Developer) – Connect on LinkedIn.

How to Build an Admin Dashboard with shadcn/ui and TanStack Start

Ajay Patel — Thu, 04 Dec 2025 16:57:05 +0000

In this guide, we’ll build a feature-rich admin dashboard using shadcn/ui for beautiful, reusable components and TanStack Start for a powerful, type-safe full-stack framework.

By the end, you’ll have:

A fully functional /dashboard layout
A statistics-rich dashboard home page with charts and tables
A Products page using TanStack Query and TanStack Table
A Settings page with profile and notification controls

Why TanStack Start?
Why shadcn/ui?
How to Build the Admin Dashboard Using shadcn/ui and TanStack Start
Live Demo & Source Code
Summary
- What’s Next?
- Resources:

Prerequisites

Before we start the guide, let’s understand the basic requirements of the project:

Node.js 18+ installed
Basic knowledge of React and TypeScript
Familiarity with TailwindCSS

What we will build

In this article, we’ll build a fully functional admin dashboard with three main sections:

Dashboard overview: A home page that displays various charts showing sales metrics, product insights widgets, and a transaction history table.
Products: A product page that demonstrates data fetching, server-side pagination, and advanced table features like column searching, sorting, and column filtering.
Settings: A user-friendly settings page with profile management and notification preferences.

The dashboard will include a responsive sidebar navigation, breadcrumb trails, a user profile dropdown, and a language selector.

Why TanStack Start?

TanStack Start is a modern full-stack React framework built on top of TanStack Router. It aims to be a flexible, type-safe alternative to traditional meta-frameworks like Next.js.

Some key benefits of TanStack Start include:

Type-safe routing and data loading
Server-side rendering (SSR) out of the box
Built on TanStack Router, with file-based routing
Great DX with TypeScript and TanStack Query integration

We’ll pair it with shadcn/ui to quickly build a polished admin dashboard.

Why shadcn/ui?

shadcn/ui is a collection of beautifully designed, accessible React components built on top of Radix UI and styled with Tailwind CSS.

Instead of installing a package, you can copy and paste the component's code directly into your project or use a CLI to generate it. This gives you full control over the code structure & styling. This approach makes Shadcn highly customizable for frameworks like TanStack Start, Next.js, Astro, and so on.

How to Build the Admin Dashboard Using shadcn/ui and TanStack Start

1. Create a new TanStack app

To get started, you’ll need to create a new TanStack Start app. You can do that with the following command:

pnpm create @tanstack/start@latest

During the CLI setup, when it asks about add-ons, make sure to select:

Shadcn
Table
Query

These will give you the shadcn/ui setup and the TanStack Query + Table integrations we’ll use later.

2. Initial Cleanup

TanStack Start’s starter template comes with some demo routes and a header we don’t need.

Clean up the project as follows:

Remove the demo folder inside the src/routes directory (or wherever your router directory lives).
Delete Header.tsx from src/components.
Remove the Header import and usage from src/routes/__root.tsx.
Clean up the src/routes/index.tsx file to something minimal (or leave a simple landing page).

At this point, you can make the initial commit to your repo.

3. Setting Up shadcn/studio Blocks

Before we set up, let’s make sure you’re clear on what the shadcn/studio and Shadcn registries are.

What is shadcn/studio?

shadcn/studio is an open-source collection of copy-and-paste shadcn/ui components, blocks, and templates. It’s paired with a powerful shadcn theme generator to help you craft, customize, and ship faster.

What is Shadcn Registry?

A shadcn registry is a system for sharing and distributing reusable code assets such as UI components, hooks, and theme configurations across different projects. Running your own registry allows you to publish your custom components that others can then use. The registry uses a registry.json file to define and organize the components and their associated files.

If you want to know more about registries, you can refer to the official documentation here.

For quick building, we will use shadcn/studio’s free shadcn block – dashboard shell.

First, configure the registries in your components.json:

{
  // ...existing config
  "registries": {
    "@shadcn-studio": "https://shadcnstudio.com/r/{name}.json",
    "@ss-components": "https://shadcnstudio.com/r/components/{name}.json",
    "@ss-blocks": "https://shadcnstudio.com/r/blocks/{name}.json",
    "@ss-themes": "https://shadcnstudio.com/r/themes/{name}.json"
  }
}

If you face any issues while setting up, you can refer to the docs.

Install the Dashboard Shell Block

To get started, visit Shadcn blocks and navigate to the Dashboard and App section. Then select the Dashboard Shell 1 block (it’s free to use).

On the top-right, you’ll see a command to install the block into your project:

Copy that command, paste it into your terminal, and run it. This will install all the components needed for the dashboard layout (sidebar, header, dropdowns, and so on).

4. Routing Structure for the Dashboard

Next, we’ll set up the dashboard routes.

First, create a new layout route for /dashboard by adding a file at:

src/routes/dashboard.tsx

Then, inside a dashboard directory, create the three pages that will live under this layout:

src/routes/dashboard/index.tsx – main dashboard overview
src/routes/dashboard/products.tsx – products table page
src/routes/dashboard/settings.tsx – settings page

Your routes folder should look like this:

src/routes/
├── __root.tsx
├── index.tsx
├── dashboard.tsx          // Layout for all /dashboard/* pages
└── dashboard/
    ├── index.tsx          // /dashboard
    ├── products.tsx       // /dashboard/products
    └── settings.tsx       // /dashboard/settings

5. Creating the `/dashboard` Layout

This will set up the layout for the dashboard. Create src/routes/dashboard.tsx and paste:

file: src/routes/dashboard.tsx

import LanguageDropdown from '@/components/shadcn-studio/blocks/dropdown-language'
import ProfileDropdown from '@/components/shadcn-studio/blocks/dropdown-profile'
import { Avatar, AvatarImage } from '@/components/ui/avatar'
import {
    Breadcrumb,
    BreadcrumbItem,
    BreadcrumbLink,
    BreadcrumbList,
    BreadcrumbPage,
    BreadcrumbSeparator
} from '@/components/ui/breadcrumb'
import { Button } from '@/components/ui/button'
import { Separator } from '@/components/ui/separator'
import {
    Sidebar,
    SidebarContent,
    SidebarGroup,
    SidebarGroupContent,
    SidebarGroupLabel,
    SidebarHeader,
    SidebarMenu,
    SidebarMenuButton,
    SidebarMenuItem,
    SidebarProvider,
    SidebarTrigger
} from '@/components/ui/sidebar'
import { createFileRoute, Link, Outlet, useLocation } from '@tanstack/react-router'
import {
    FacebookIcon,
    InstagramIcon,
    LanguagesIcon,
    LayoutDashboard,
    LinkedinIcon,
    LogIn,
    Package,
    Settings,
    TwitterIcon,
    User2
} from 'lucide-react'
import React from 'react'

export const Route = createFileRoute('/dashboard')({
    component: DashboardLayout
})

function DashboardLayout() {
    const location = useLocation()
    const pathSegments = location.pathname.split('/').filter(Boolean)

    return (
        'flex min-h-dvh w-full'>
            
                
                    
                        
                            
                                
                                    "lg" asChild>
                                        "/">
                                            "flex aspect-square size-8 items-center justify-center rounded-lg bg-primary text-primary-foreground">
                                                "size-4" />
                                            
                                            "grid flex-1 text-left text-sm leading-tight">
                                                "truncate font-semibold">Your App
                                                "truncate text-xs">Dashboard
                                            
                                        
                                    
                                
                            
                        

                        
                            General
                            
                                
                                    
                                        
                                            '/dashboard'>
                                                
                                                Dashboard
                                            
                                        
                                    
                                    
                                        
                                            '/dashboard/products'>
                                                
                                                Products
                                            
                                        
                                    
                                    
                                        
                                            '/dashboard/settings'>
                                                
                                                Settings
                                            
                                        
                                    
                                
                            
                        
                    
                
                'flex flex-1 flex-col'>
                    'bg-card sticky top-0 z-50 border-b'>
                        'mx-auto flex max-w-7xl items-center justify-between gap-6 px-4 py-2 sm:px-6'>
                            'flex items-center gap-4'>
                                '[&_svg]:h-5 [&_svg]:w-5' />
                                'vertical' className='hidden h-4 sm:block' />
                                'hidden sm:block'>
                                    
                                        
                                            
                                                '/'>Home
                                            
                                        
                                        
                                        {pathSegments.map((segment, index) => {
                                            const path = `/${pathSegments.slice(0, index + 1).join('/')}`
                                            const isLast = index === pathSegments.length - 1
                                            const title = segment.charAt(0).toUpperCase() + segment.slice(1)

                                            return (
                                                
                                                    
                                                        {isLast ? (
                                                            {title}
                                                        ) : (
                                                            
                                                                as any}>{title}
                                                            
                                                        )}
                                                    
                                                    {!isLast && }
                                                
                                            )
                                        })}
                                    
                                
                            
                            'flex items-center gap-1.5'>
                                'ghost' size='icon'>
                                            
                                        
                                    }
                                />
                                'ghost' size='icon' className='h-10 w-10'>
                                            'h-10 w-10 rounded-md'>
                                                'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-1.png' />
                                            
                                        
                                    }
                                />
                            
                        
                    
                    'mx-auto w-full max-w-7xl flex-1 px-4 py-6 sm:px-6'>
                        
                    
                    
                        'text-muted-foreground mx-auto flex w-full items-center justify-between gap-3 px-4 py-3 flex-col sm:flex-row sm:gap-6 sm:px-6'>
                            'text-sm text-center sm:text-left'>
                                {`©${new Date().getFullYear()}`}{' '}
                                '#' className='text-primary'>
                                    TanStack Start
                                
                                , Made for better web design
                            
                            'flex items-center gap-5'>
                                '#'>
                                    'h-4 w-4' />
                                
                                '#'>
                                    'h-4 w-4' />
                                
                                '#'>
                                    'h-4 w-4' />
                                
                                '#'>
                                    'h-4 w-4' />
                                
                            
                        
                    
                
            
        
    )
}

You now have a full layout for all /dashboard/* routes.

Let's break down the key parts of our dashboard layout:

Sidebar structure: The component wraps our navigation menu. Inside, we use and to create navigation links. Each menu item uses TanStack Router's component for type-safe navigation. We also have a header set up in the
Dynamic breadcrumbs: The breadcrumb section uses location.pathname to split the current URL into segments, then maps over them to create breadcrumb links. The isLast check ensures the final breadcrumb renders as plain text rather than a link.
Header actions: The header includes two dropdowns: for internationalization and for user account actions. These come from the shadcn/studio blocks we installed.
Outlet component: The component is where child routes (like /dashboard, /dashboard/products) will render. This makes our layout reusable across all dashboard pages. The layout uses Tailwind's utility classes for spacing, colors, and responsive behavior, making it easy to customize for your use case.

For more details regarding the Sidebar component, you can refer to the official docs here.

You now have a full layout for all /dashboard/* routes.

6. Building the Dashboard Home Page

Create src/routes/dashboard/index.tsx:

import { type Item } from '@/components/shadcn-studio/blocks/datatable-transaction'
import { createFileRoute } from '@tanstack/react-router'

import { Card } from '@/components/ui/card'

import SalesMetricsCard from '@/components/shadcn-studio/blocks/chart-sales-metrics'
import TransactionDatatable from '@/components/shadcn-studio/blocks/datatable-transaction'
import StatisticsCard from '@/components/shadcn-studio/blocks/statistics-card-01'
import ProductInsightsCard from '@/components/shadcn-studio/blocks/widget-product-insights'
import TotalEarningCard from '@/components/shadcn-studio/blocks/widget-total-earning'

import {
    CalendarX2Icon,
    TriangleAlertIcon,
    TruckIcon
} from 'lucide-react'

// Statistics card data
const StatisticsCardData = [
    {
        icon: 'h-4 w-4' />,
        value: '42',
        title: 'Shipped Orders',
        changePercentage: '+18.2%'
    },
    {
        icon: 'h-4 w-4' />,
        value: '8',
        title: 'Damaged Returns',
        changePercentage: '-8.7%'
    },
    {
        icon: 'h-4 w-4' />,
        value: '27',
        title: 'Missed Delivery Slots',
        changePercentage: '+4.3%'
    }
]

// Earning data for Total Earning card
const earningData = [
    {
        img: 'https://cdn.shadcnstudio.com/ss-assets/blocks/dashboard-application/widgets/zipcar.png',
        platform: 'Zipcar',
        technologies: 'Vuejs & HTML',
        earnings: '-$23,569.26',
        progressPercentage: 75
    },
    {
        img: 'https://cdn.shadcnstudio.com/ss-assets/blocks/dashboard-application/widgets/bitbank.png',
        platform: 'Bitbank',
        technologies: 'Figma & React',
        earnings: '-$12,650.31',
        progressPercentage: 25
    }
]

// Transaction table data
const transactionData: Item[] = [
    {
        id: '1',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-1.png',
        avatarFallback: 'JA',
        name: 'Jack Alfredo',
        amount: 315.0,
        status: 'paid',
        email: 'jack@shadcnstudio.com',
        paidBy: 'mastercard'
    },
    {
        id: '2',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-2.png',
        avatarFallback: 'MG',
        name: 'Maria Gonzalez',
        amount: 253.4,
        status: 'pending',
        email: 'maria.g@shadcnstudio.com',
        paidBy: 'visa'
    },
    {
        id: '3',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-3.png',
        avatarFallback: 'JD',
        name: 'John Doe',
        amount: 852.0,
        status: 'paid',
        email: 'john.doe@shadcnstudio.com',
        paidBy: 'mastercard'
    },
    {
        id: '4',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-4.png',
        avatarFallback: 'EC',
        name: 'Emily Carter',
        amount: 889.0,
        status: 'pending',
        email: 'emily.carter@shadcnstudio.com',
        paidBy: 'visa'
    },
    {
        id: '5',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png',
        avatarFallback: 'DL',
        name: 'David Lee',
        amount: 723.16,
        status: 'paid',
        email: 'david.lee@shadcnstudio.com',
        paidBy: 'mastercard'
    },
    {
        id: '6',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-6.png',
        avatarFallback: 'SP',
        name: 'Sophia Patel',
        amount: 612.0,
        status: 'failed',
        email: 'sophia.patel@shadcnstudio.com',
        paidBy: 'mastercard'
    },
    {
        id: '7',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-7.png',
        avatarFallback: 'RW',
        name: 'Robert Wilson',
        amount: 445.25,
        status: 'paid',
        email: 'robert.wilson@shadcnstudio.com',
        paidBy: 'visa'
    },
    {
        id: '8',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-8.png',
        avatarFallback: 'LM',
        name: 'Lisa Martinez',
        amount: 297.8,
        status: 'processing',
        email: 'lisa.martinez@shadcnstudio.com',
        paidBy: 'mastercard'
    },
    {
        id: '9',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-9.png',
        avatarFallback: 'MT',
        name: 'Michael Thompson',
        amount: 756.9,
        status: 'paid',
        email: 'michael.thompson@shadcnstudio.com',
        paidBy: 'visa'
    },
    {
        id: '10',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-10.png',
        avatarFallback: 'AJ',
        name: 'Amanda Johnson',
        amount: 189.5,
        status: 'pending',
        email: 'amanda.johnson@shadcnstudio.com',
        paidBy: 'mastercard'
    },
    {
        id: '11',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-11.png',
        avatarFallback: 'KB',
        name: 'Kevin Brown',
        amount: 1024.75,
        status: 'paid',
        email: 'kevin.brown@shadcnstudio.com',
        paidBy: 'visa'
    },
    {
        id: '12',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-12.png',
        avatarFallback: 'SD',
        name: 'Sarah Davis',
        amount: 367.2,
        status: 'failed',
        email: 'sarah.davis@shadcnstudio.com',
        paidBy: 'mastercard'
    },
    {
        id: '13',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-13.png',
        avatarFallback: 'CG',
        name: 'Christopher Garcia',
        amount: 598.45,
        status: 'processing',
        email: 'christopher.garcia@shadcnstudio.com',
        paidBy: 'visa'
    },
    {
        id: '14',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-14.png',
        avatarFallback: 'JR',
        name: 'Jennifer Rodriguez',
        amount: 821.3,
        status: 'paid',
        email: 'jennifer.rodriguez@shadcnstudio.com',
        paidBy: 'mastercard'
    },
    {
        id: '15',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-15.png',
        avatarFallback: 'DM',
        name: 'Daniel Miller',
        amount: 156.75,
        status: 'pending',
        email: 'daniel.miller@shadcnstudio.com',
        paidBy: 'visa'
    },
    {
        id: '16',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-16.png',
        avatarFallback: 'NW',
        name: 'Nicole White',
        amount: 934.1,
        status: 'paid',
        email: 'nicole.white@shadcnstudio.com',
        paidBy: 'mastercard'
    },
    {
        id: '17',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-17.png',
        avatarFallback: 'AL',
        name: 'Anthony Lopez',
        amount: 412.85,
        status: 'failed',
        email: 'anthony.lopez@shadcnstudio.com',
        paidBy: 'visa'
    },
    {
        id: '18',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-18.png',
        avatarFallback: 'MH',
        name: 'Michelle Harris',
        amount: 675.5,
        status: 'processing',
        email: 'michelle.harris@shadcnstudio.com',
        paidBy: 'mastercard'
    },
    {
        id: '19',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-19.png',
        avatarFallback: 'JC',
        name: 'James Clark',
        amount: 289.95,
        status: 'paid',
        email: 'james.clark@shadcnstudio.com',
        paidBy: 'visa'
    },
    {
        id: '20',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-20.png',
        avatarFallback: 'RL',
        name: 'Rachel Lewis',
        amount: 1156.25,
        status: 'pending',
        email: 'rachel.lewis@shadcnstudio.com',
        paidBy: 'mastercard'
    },
    {
        id: '21',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-21.png',
        avatarFallback: 'TY',
        name: 'Thomas Young',
        amount: 543.6,
        status: 'paid',
        email: 'thomas.young@shadcnstudio.com',
        paidBy: 'visa'
    },
    {
        id: '22',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-22.png',
        avatarFallback: 'SB',
        name: 'Stephanie Brown',
        amount: 789.3,
        status: 'processing',
        email: 'stephanie.brown@shadcnstudio.com',
        paidBy: 'mastercard'
    },
    {
        id: '23',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-23.png',
        avatarFallback: 'BM',
        name: 'Brandon Moore',
        amount: 425.75,
        status: 'failed',
        email: 'brandon.moore@shadcnstudio.com',
        paidBy: 'visa'
    },
    {
        id: '24',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-24.png',
        avatarFallback: 'KT',
        name: 'Kelly Taylor',
        amount: 1203.5,
        status: 'paid',
        email: 'kelly.taylor@shadcnstudio.com',
        paidBy: 'mastercard'
    },
    {
        id: '25',
        avatar: 'https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-25.png',
        avatarFallback: 'MA',
        name: 'Mark Anderson',
        amount: 356.2,
        status: 'pending',
        email: 'mark.anderson@shadcnstudio.com',
        paidBy: 'visa'
    }
]

export const Route = createFileRoute('/dashboard/')({
    component: RouteComponent,
})

function RouteComponent() {
    return (
        'grid grid-cols-2 gap-6 lg:grid-cols-3'>
            {/* Statistics Cards */}
            'col-span-full grid gap-6 sm:grid-cols-3 md:max-lg:grid-cols-1'>
                {StatisticsCardData.map((card, index) => (
                    
                ))}
            

            'grid gap-6 max-xl:col-span-full lg:max-xl:grid-cols-2'>
                {/* Product Insights Card */}
                'justify-between gap-3 *:data-[slot=card-content]:space-y-5' />

                {/* Total Earning Card */}
                'Total Earning'
                    earning={24650}
                    trend='up'
                    percentage={10}
                    comparisonText='Compare to last year ($84,325)'
                    earningData={earningData}
                    className='justify-between gap-5 sm:min-w-0 *:data-[slot=card-content]:space-y-7'
                />
            

            'col-span-full xl:col-span-2 *:data-[slot=card-content]:space-y-6' />
            'col-span-full w-full py-0'>
                
            
        
    )
}

Our dashboard homepage uses various shadcn-studio blocks like:

Statistics cards display KPIs (Shipped Orders, Damaged Returns, and so on) with trend indicators. Each card receives props for the icon, value, title, and percentage change, making them reusable for any metric.
Chart components like use recharts under the hood to visualize data. The styling comes from shadcn/ui's card component and Tailwind utilities.
Transaction data table demonstrates TanStack Table integration. We pass an array of transaction objects, and the component handles rendering, sorting, and pagination. Notice how we use TypeScript's Item[] type for full type safety.

If you now navigate to /dashboard, you should see an admin dashboard with KPI statistics, charts, a dashboard, and a transaction table. Here is what it would look like:

We have built this beautiful dashboard quickly by using the shadcn/studio’s pre-built blocks.

7. Set up the Products Page.

Before building our products table, we need to install Zod, a TypeScript-first schema validation library. We'll use it to validate the data structure of requests to our server function.

Why Zod?

TanStack Start's server functions use Zod to ensure type-safe data transfer between client and server. When we request to fetch products, Zod validates that the request includes the correct types for page, pageSize, sortBy, and filters. This catches errors at runtime and provides excellent TypeScript inference.

Now, let’s set up the products page with a products table. But before that, let’s install the zod package dependency. Here is the command for it:

pnpm add zod

Creating Mock Product Data

We will need to store our mock products’ data somewhere. For that, we will create a new file data/products.ts and paste the code below. This will help us mock the product data for our products table.

import { createServerFn } from "@tanstack/react-start";
import { z } from "zod";

export type Product = {
    id: string
    name: string
    category: string
    price: number
    stock: number
    status: 'active' | 'draft' | 'archived'
    image: string
}

// Define the type for the data parameter
type ProductQueryParams = {
    page: number;
    pageSize: number;
    sortBy?: string;
    sortOrder?: "asc" | "desc";
    filters?: {
        name?: string;
        category?: string;
        status?: string;
    };
};

const products: Product[] = [
    {
        id: 'PROD-001',
        name: 'Wireless Noise Cancelling Headphones',
        category: 'Electronics',
        price: 299.99,
        stock: 45,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1505740420928-5e560c06d30e?w=100&q=80',
    },
    {
        id: 'PROD-002',
        name: 'Ergonomic Office Chair',
        category: 'Furniture',
        price: 199.50,
        stock: 12,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1592078615290-033ee584e267?w=100&q=80',
    },
    {
        id: 'PROD-003',
        name: 'Mechanical Gaming Keyboard',
        category: 'Electronics',
        price: 129.99,
        stock: 0,
        status: 'archived',
        image: 'https://images.unsplash.com/photo-1587829741301-dc798b91add1?w=100&q=80',
    },
    {
        id: 'PROD-004',
        name: 'Smart Fitness Watch',
        category: 'Wearables',
        price: 149.00,
        stock: 89,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1523275335684-37898b6baf30?w=100&q=80',
    },
    {
        id: 'PROD-005',
        name: 'Minimalist Desk Lamp',
        category: 'Lighting',
        price: 45.00,
        stock: 23,
        status: 'draft',
        image: 'https://images.unsplash.com/photo-1507473888900-52e1ad14723b?w=100&q=80',
    },
    {
        id: 'PROD-006',
        name: 'Portable Bluetooth Speaker',
        category: 'Electronics',
        price: 79.99,
        stock: 150,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1608043152269-423dbba4e7e1?w=100&q=80',
    },
    {
        id: 'PROD-007',
        name: 'Ceramic Coffee Mug Set',
        category: 'Kitchen',
        price: 24.99,
        stock: 200,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1514228742587-6b1558fcca3d?w=100&q=80',
    },
    {
        id: 'PROD-008',
        name: 'Leather Messenger Bag',
        category: 'Accessories',
        price: 129.50,
        stock: 15,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1553062407-98eeb64c6a62?w=100&q=80',
    },
    {
        id: 'PROD-009',
        name: 'Wireless Charging Pad',
        category: 'Electronics',
        price: 39.99,
        stock: 75,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1586816879360-004f5b0c51e3?w=100&q=80',
    },
    {
        id: 'PROD-010',
        name: 'Succulent Plant Set',
        category: 'Home & Garden',
        price: 29.99,
        stock: 30,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1485955900006-10f4d324d411?w=100&q=80',
    },
    {
        id: 'PROD-011',
        name: 'Professional Chef Knife',
        category: 'Kitchen',
        price: 89.95,
        stock: 42,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1593618998160-e34014e67546?w=100&q=80',
    },
    {
        id: 'PROD-012',
        name: 'Yoga Mat',
        category: 'Fitness',
        price: 35.00,
        stock: 100,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1601925260368-ae2f83cf8b7f?w=100&q=80',
    },
    {
        id: 'PROD-013',
        name: 'Smart Thermostat',
        category: 'Home Automation',
        price: 199.00,
        stock: 0,
        status: 'archived',
        image: 'https://images.unsplash.com/photo-1567789884554-0b844b597180?w=100&q=80',
    },
    {
        id: 'PROD-014',
        name: 'Vintage Film Camera',
        category: 'Photography',
        price: 450.00,
        stock: 3,
        status: 'draft',
        image: 'https://images.unsplash.com/photo-1526170375885-4d8ecf77b99f?w=100&q=80',
    },
    {
        id: 'PROD-015',
        name: 'Cotton T-Shirt Pack',
        category: 'Apparel',
        price: 49.99,
        stock: 150,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1521572163474-6864f9cf17ab?w=100&q=80',
    },
    {
        id: 'PROD-016',
        name: 'Electric Toothbrush',
        category: 'Personal Care',
        price: 69.99,
        stock: 55,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1559656914-a30970c1affd?w=100&q=80',
    },
    {
        id: 'PROD-017',
        name: 'Gaming Mouse',
        category: 'Electronics',
        price: 59.99,
        stock: 88,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1527864550417-7fd91fc51a46?w=100&q=80',
    },
    {
        id: 'PROD-018',
        name: 'Essential Oil Diffuser',
        category: 'Home & Garden',
        price: 34.50,
        stock: 25,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1602928321679-560bb453f190?w=100&q=80',
    },
    {
        id: 'PROD-019',
        name: 'Running Shoes',
        category: 'Footwear',
        price: 119.99,
        stock: 60,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1542291026-7eec264c27ff?w=100&q=80',
    },
    {
        id: 'PROD-020',
        name: 'Digital Drawing Tablet',
        category: 'Electronics',
        price: 249.00,
        stock: 18,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1561525140-c2a4cc68e4bd?w=100&q=80',
    },
    {
        id: 'PROD-021',
        name: 'Bamboo Cutting Board',
        category: 'Kitchen',
        price: 22.99,
        stock: 95,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1594385208974-2e75f8d7bb48?w=100&q=80',
    },
    {
        id: 'PROD-022',
        name: 'Sunglasses',
        category: 'Accessories',
        price: 159.00,
        stock: 40,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1511499767150-a48a237f0083?w=100&q=80',
    },
    {
        id: 'PROD-023',
        name: 'Water Bottle',
        category: 'Fitness',
        price: 19.99,
        stock: 300,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1602143407151-01114192003f?w=100&q=80',
    },
    {
        id: 'PROD-024',
        name: 'Throw Pillow Set',
        category: 'Home Decor',
        price: 45.99,
        stock: 28,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1584100936595-c0654b55a2e6?w=100&q=80',
    },
    {
        id: 'PROD-025',
        name: 'Wireless Earbuds',
        category: 'Electronics',
        price: 89.99,
        stock: 120,
        status: 'active',
        image: 'https://images.unsplash.com/photo-1590658268037-6bf12165a8df?w=100&q=80',
    }
]

export const getProducts = createServerFn({ method: "GET" })
    .inputValidator(
        z.object({
            page: z.number().default(0),
            pageSize: z.number().default(10),
            sortBy: z.string().optional(),
            sortOrder: z.enum(["asc", "desc"]).optional(),
            filters: z
                .object({
                    name: z.string().optional(),
                    category: z.string().optional(),
                    status: z.string().optional(),
                })
                .optional(),
        })
    )
    .handler(async ({ data }: { data: ProductQueryParams }) => {
        const { page, pageSize, sortBy, sortOrder, filters } = data;

        // Apply filters
        let filteredProducts = [...products];

        if (filters) {
            if (filters.name) {
                filteredProducts = filteredProducts.filter((product) =>
                    product.name.toLowerCase().includes(filters.name!.toLowerCase())
                );
            }

            if (filters.category) {
                filteredProducts = filteredProducts.filter(
                    (product) =>
                        product.category.toLowerCase() === filters.category!.toLowerCase()
                );
            }

            if (filters.status) {
                filteredProducts = filteredProducts.filter(
                    (product) => product.status === filters.status
                );
            }
        }

        // Apply sorting
        if (sortBy) {
            filteredProducts.sort((a, b) => {
                const aValue = a[sortBy as keyof Product];
                const bValue = b[sortBy as keyof Product];

                if (typeof aValue === "string" && typeof bValue === "string") {
                    return sortOrder === "desc"
                        ? bValue.localeCompare(aValue)
                        : aValue.localeCompare(bValue);
                }

                if (typeof aValue === "number" && typeof bValue === "number") {
                    return sortOrder === "desc" ? bValue - aValue : aValue - bValue;
                }

                return 0;
            });
        }

        // Calculate pagination
        const totalCount = filteredProducts.length;
        const totalPages = Math.ceil(totalCount / pageSize);
        const paginatedProducts = filteredProducts.slice(
            page * pageSize,
            (page + 1) * pageSize
        );

        // Simulate network delay
        await new Promise((resolve) => setTimeout(resolve, 500));

        return {
            products: paginatedProducts,
            pagination: {
                page,
                pageSize,
                totalCount,
                totalPages,
            },
        };
    });

Let’s understand the server function and break down what's happening in getProducts:

Input validation: The .inputValidator() method uses a Zod schema to validate incoming requests. It ensures page and pageSize are numbers, sortOrder is either "asc" or "desc", and filters are optional strings.
Filtering products: The function filters the products array based on the provided filters (name, category, status). This simulates what a real database query would do.
Sorting: Products are sorted by the specified column (sortBy) in ascending or descending order (sortOrder).
Pagination: We calculate which slice of products to return based on page and pageSize, along with metadata like totalCount and totalPages.

Create the Products table:

Once the data is done, let’s create a table in /dashboard/products.tsx. This table will use our mock product data and will provide multiple functions in the table, like search, sort, and filter. This table demonstrates the powerful combination of TanStack Query for data management and TanStack Table for rendering.

Paste the code below in the products.tsx file:

import { useQuery } from '@tanstack/react-query'
import { createFileRoute } from '@tanstack/react-router'
import {
    ColumnDef,
    ColumnFiltersState,
    flexRender,
    getCoreRowModel,
    getFilteredRowModel,
    getPaginationRowModel,
    getSortedRowModel,
    SortingState,
    useReactTable,
    VisibilityState,
} from '@tanstack/react-table'
import {
    ArrowUpDown,
    ChevronDown,
    Filter,
    Loader2,
    MoreHorizontal,
    Plus,
    Search
} from 'lucide-react'
import { useState } from 'react'

import { Badge } from '@/components/ui/badge'
import { Button } from '@/components/ui/button'
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
import {
    DropdownMenu,
    DropdownMenuCheckboxItem,
    DropdownMenuContent,
    DropdownMenuItem,
    DropdownMenuLabel,
    DropdownMenuSeparator,
    DropdownMenuTrigger,
} from '@/components/ui/dropdown-menu'
import { Input } from '@/components/ui/input'
import {
    Table,
    TableBody,
    TableCell,
    TableHead,
    TableHeader,
    TableRow,
} from '@/components/ui/table'
import { getProducts, type Product } from '@/data/products'

export const Route = createFileRoute('/dashboard/products')({
    component: ProductsPage,
})

export const columns: ColumnDef[] = [
    {
        accessorKey: 'name',
        header: ({ column }) => {
            return (
                
            )
        },
        cell: ({ row }) => (
            "flex items-center gap-3">
                'name')}
                    className="h-10 w-10 rounded-md object-cover"
                />
                "flex flex-col">
                    "font-medium">{row.getValue('name')}
                    "text-xs text-muted-foreground">{row.original.id}
                
            
        ),
    },
    {
        accessorKey: 'category',
        header: 'Category',
        cell: ({ row }) => {row.getValue('category')},
    },
    {
        accessorKey: 'status',
        header: 'Status',
        cell: ({ row }) => {
            const status = row.getValue('status') as string
            return (
                'active' ? 'default' : status === 'draft' ? 'secondary' : 'outline'}>
                    {status}
                
            )
        },
    },
    {
        accessorKey: 'price',
        header: () => "text-right">Price,
        cell: ({ row }) => {
            const amount = parseFloat(row.getValue('price'))
            const formatted = new Intl.NumberFormat('en-US', {
                style: 'currency',
                currency: 'USD',
            }).format(amount)

            return "text-right font-medium">{formatted}
        },
    },
    {
        accessorKey: 'stock',
        header: () => "text-right">Stock,
        cell: ({ row }) => {
            const stock = parseFloat(row.getValue('stock'))
            return ${stock === 0 ? 'text-red-500 font-medium' : ''}`}>{stock}
        },
    },
    {
        id: 'actions',
        enableHiding: false,
        cell: ({ row }) => {
            const product = row.original

            return (
                
                    
                        
                    
                    "end">
                        Actions
                         navigator.clipboard.writeText(product.id)}
                        >
                            Copy Product ID
                        
                        
                        Edit Product
                        View Details
                    
                
            )
        },
    },
]

function ProductsPage() {
    const [sorting, setSorting] = useState([])
    const [columnFilters, setColumnFilters] = useState([])
    const [columnVisibility, setColumnVisibility] = useState({})
    const [rowSelection, setRowSelection] = useState({})
    const [pagination, setPagination] = useState({
        pageIndex: 0,
        pageSize: 10,
    })

    const { data, isLoading } = useQuery({
        queryKey: ['products', pagination, sorting, columnFilters],
        queryFn: () => getProducts({
            data: {
                page: pagination.pageIndex,
                pageSize: pagination.pageSize,
                sortBy: sorting[0]?.id,
                sortOrder: sorting[0]?.desc ? 'desc' : 'asc',
                filters: {
                    name: (columnFilters.find((f) => f.id === 'name')?.value as string) || undefined,
                    status: (columnFilters.find((f) => f.id === 'status')?.value as string) || undefined,
                }
            }
        }),
    })

    const products = data?.products || []
    const totalPages = data?.pagination.totalPages || 0
    const totalCount = data?.pagination.totalCount || 0

    const table = useReactTable({
        data: products,
        columns,
        pageCount: totalPages,
        manualPagination: true,
        manualSorting: true,
        manualFiltering: true,
        onSortingChange: setSorting,
        onColumnFiltersChange: setColumnFilters,
        getCoreRowModel: getCoreRowModel(),
        getPaginationRowModel: getPaginationRowModel(),
        getSortedRowModel: getSortedRowModel(),
        getFilteredRowModel: getFilteredRowModel(),
        onColumnVisibilityChange: setColumnVisibility,
        onRowSelectionChange: setRowSelection,
        onPaginationChange: setPagination,
        state: {
            sorting,
            columnFilters,
            columnVisibility,
            rowSelection,
            pagination,
        },
    })

    return (
        "w-full space-y-4">
            "flex items-center justify-between">
                "text-2xl font-bold tracking-tight">Products
                "flex items-center gap-2">
                    
                    
                
            

            
                
                    Product Management
                    
                        Manage your product catalog, track inventory, and update prices.
                    
                
                
                    "flex items-center py-4 gap-2">
                        "relative flex-1">
                            "absolute left-2 top-2.5 h-4 w-4 text-muted-foreground" />
                            "Filter products..."
                                value={(table.getColumn("name")?.getFilterValue() as string) ?? ""}
                                onChange={(event) =>
                                    table.getColumn("name")?.setFilterValue(event.target.value)
                                }
                                className="pl-8 max-w-sm"
                            />
                        
                        
                            
                                
                            
                            "end">
                                {table
                                    .getAllColumns()
                                    .filter((column) => column.getCanHide())
                                    .map((column) => {
                                        return (
                                            "capitalize"
                                                checked={column.getIsVisible()}
                                                onCheckedChange={(value) =>
                                                    column.toggleVisibility(!!value)
                                                }
                                            >
                                                {column.id}
                                            
                                        )
                                    })}
                            
                        
                    
                    "rounded-md border">
                        
                                {table.getHeaderGroups().map((headerGroup) => (
                                    
                                        {headerGroup.headers.map((header) => {
                                            return (
                                                
                                                    {header.isPlaceholder
                                                        ? null
                                                        : flexRender(
                                                            header.column.columnDef.header,
                                                            header.getContext()
                                                        )}
                                                
                                            )
                                        })}
                                    
                                ))}
                            
                                {isLoading ? (
                                    
                                        "h-24 text-center">
                                            "flex items-center justify-center gap-2">
                                                "h-6 w-6 animate-spin" />
                                                Loading products...
                                            
                                        
                                    
                                ) : table.getRowModel().rows?.length ? (
                                    table.getRowModel().rows.map((row) => (
                                        "selected"}
                                        >
                                            {row.getVisibleCells().map((cell) => (
                                                
                                                    {flexRender(
                                                        cell.column.columnDef.cell,
                                                        cell.getContext()
                                                    )}
                                                
                                            ))}
                                        
                                    ))
                                ) : (
                                    
                                        "h-24 text-center"
                                        >
                                            No results.
                                        
                                    
                                )}
                            
                            
                            
                        
                    
                    "flex items-center justify-end space-x-2 py-4">
                        "flex-1 text-sm text-muted-foreground">
                            {table.getFilteredSelectedRowModel().rows.length} of{" "}
                            {totalCount} row(s) selected.
                        
                        "space-x-2">
                            
                            
                        
                    
                
            
        
    )
}

Now you can see the fully functional products page by navigating the /products where you can search and sort the products.

How do TanStack Query and TanStack Table Work in the products table?

Our products page uses TanStack Query for data fetching and TanStack Table for rendering.

useQuery is a fundamental hook in TanStack Query for managing server state in web applications. It simplifies data fetching, caching, and synchronization.

The below code snippet below shows how we have used useQuery in our product table:

import { useQuery } from '@tanstack/react-query';

const { data, isLoading } = useQuery({
    queryKey: ['products', pagination, sorting, columnFilters],
    queryFn: () => getProducts({...})
}

The useQuery hook manages data fetching in our application. For more details, you can refer to the official docs here.

useReactTable:

import { useReactTable } from '@tanstack/react-table'

const table = useReactTable({
    data: products,
    columns,
    manualPagination: true,
    manualSorting: true,
    manualFiltering: true,
})

TanStack Table manages the UI state and rendering. By setting manualPagination, manualSorting, and manualFiltering to true, we tell the table that server-side logic handles these operations.

When users sort, filter, or paginate, the table updates its states, and React Query detects the state change in the queryKey. It refetches data from the server, and the table re-renders with fresh data.

This architecture is production-ready and scales to thousands of rows. You just need to replace the mock API endpoint with your real API endpoint.

8. Settings Page

Finally, let’s add a simple Settings page with a profile section and some basic notification preferences.

Below is the code for the Settings Page. You can paste it into /dashboard/settings.tsx:

import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar'
import { Button } from '@/components/ui/button'
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from '@/components/ui/card'
import { Checkbox } from "@/components/ui/checkbox"
import { Input } from '@/components/ui/input'
import { Separator } from '@/components/ui/separator'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/dashboard/settings')({
  component: SettingsPage,
})

function SettingsPage() {
  return (
    "space-y-6">
      
        "text-lg font-medium">Settings
        "text-sm text-muted-foreground">
          Manage your account settings and set e-mail preferences.
        
      
      

      "grid gap-6">
        
          
            Profile
            
              This is how others will see you on the site.
            
          
          "space-y-4">
            "flex items-center gap-4">
              "h-20 w-20">
                "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-1.png" />
                JD
              
              
            
            "space-y-1">
              "username" className="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70">Username
              "username" defaultValue="jdoe" />
            
            "space-y-1">
              "email" className="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70">Email
              "email" defaultValue="john.doe@example.com" />
            
            "space-y-1">
              "bio" className="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70">Bio
              "bio" placeholder="Tell us a little bit about yourself" />
            
          
          
            
          
        

        
          
            Notifications
            
              Configure how you receive notifications.
            
          
          "space-y-4">
            "flex items-center justify-between rounded-lg border p-4">
              "space-y-0.5">
                "text-base font-medium">Communication emails
                "text-sm text-muted-foreground">
                  Receive emails about your account activity.
                
              
              {/* Toggle would go here, using a simple checkbox for now */}
              
            
            "flex items-center justify-between rounded-lg border p-4">
              "space-y-0.5">
                "text-base font-medium">Marketing emails
                "text-sm text-muted-foreground">
                  Receive emails about new products, features, and more.
                
              
              
            
          
          
            
          
        
      
    
  )
}

In this page, we have created two sections:

Profile Section
Notification Section

These two sections have been built using shadcn/ui components like Card, Footer, Checkbox, Avatar, Input, and so on.

At this point, we have:

A dashboard layout with sidebar, header, breadcrumbs, and footer
A Dashboard page with charts, insights, and a transaction table
A Products page powered by:
- TanStack Start server functions
- TanStack Query
- TanStack Table
A clean Settings page using shadcn/ui components

Live Demo & Source Code

You can check out the full source code on GitHub here:

GitHub Repository: https://github.com/themeselection/tanstack-dashboard-demo
Live Demo: https://tanstack-dashboard-demo.vercel.app/dashboard

Feel free to clone, experiment, and extend it to fit your own application needs!

Summary

Congratulations! You've built a complete, production-ready admin dashboard using TanStack Start, TanStack Table, TanStack Query, Shadcn/ui, and shadcn/studio.

Throughout this tutorial, you’ve gained some hands-on experience in:

Full-stack application development with type safety: We’ve developed a full-stack application with TanStack Start's server functions with Zod validation to create type-safe APIs.
Advanced data fetching: We’ve implemented TanStack Query for data fetching with automatic caching and background updates.
Complex table interactions: We’ve built feature-rich data tables with TanStack Table, including server-side pagination, sorting, and filtering.
Building UI quicker: We’ve leveraged shadcn/ui and shadcn/studio blocks to quickly build polished interfaces.
Responsive layouts: And we’ve created adaptive designs that work seamlessly from mobile to desktop

What’s Next?

Now that you have a solid foundation, consider implementing some or all of the below features if you want to work more on this:

Authentication: Add user authentication with Clerk, NextAuth, or Auth.js
Real database: Replace mock data with Prisma + PostgreSQL or Drizzle + SQLite
Form validation: Integrate React Hook Form with Zod for robust form handling
Theming: Implement dark mode and custom color schemes using shadcn/ui's theming system
API routes for CRUD: Add CRUD operations for products (create, update, delete)
Internationalization: Make the dashboard compatible with multiple languages by integrating internationalization.

We shipped a scalable and production-ready dashboard much faster than starting from scratch. Hope you enjoyed the process – and thanks for reading!

Resources:

How to Set Up a Registry in shadcn

Abhijeet Dave — Mon, 27 Oct 2025 14:27:20 +0000

In this guide, you’ll learn how to set up a registry in shadcn. If you’re not familiar with this tool, shadcn is a collection of reusable and accessible components you can use in your projects.

You’ll learn about essential concepts such as setting up and configuring the registry, adding authentication, CLI commands you can use, and more.

What is a registry in shadcn?

A registry in shadcn is a central place for sharing and managing your reusable components, utilities, and UI elements (along with other resources) across different projects. It lets developers give numbers to and organize components in a standard way. This makes it easier to integrate and share resources within and across teams.

The registry system helps make these components easily reusable. It also helps teams keep their code clean and manage dependencies more effectively.

shadcn's main system uses the registry.json file. The file provides key information about the registry, such as resource names and places along with the files that go with them.

Why use a shadcn registry?

Using registries is helpful because it helps you standardize rules for your components. Every component, UI element, or utility follows a clear plan, which makes it easier to integrate and manage them.

Also, version numbers let you manage different versions of a component. This makes sure various parts work together and lets you update them without trouble.

Registries also give you the ability to organize resources into groups while managing what depends on what. Everything is flexible this way.

And if you create a registry, it lets you share your components with other developers (either everyone or just certain people). This allows for both inside and open-source work.

How to Create and Configure Your Registry

Creating a shadcn registry involves setting up a configuration file (registry.json) at the root of your project. This file contains the metadata and structure of your registry, helping define components and their relationships.

shadcn provides this starter template to help you understand how registries work.

Step by Step Guide to Create a Registry

1. Define the Registry's Metadata

You’ll need to fill in the following information:

name: A unique name for the registry.
homepage: A URL pointing to the homepage for the registry.
items: An array that contains all available components, UI elements, or utilities in the registry.

Here’s an example of a simple registry.json:

{
  "$schema": "",
  "name": "acme",
  "homepage": "",
  "items": [
    // Components will go here
  ]
}

2. Components Structure

Each item in the registry can be a component, theme, hook, or utility. These items have the following properties:

name: Unique name of the component.
type: Specifies the type of item (for example, registry:component, registry:block).
files: An array of files that make up the component.

Here’s an example:

{
  "name": "name",
  "type": "registry:block",
  "title": "title",
  "description": "Simple description",
  "files": [
    {
      "path": "registry/new-york/...",
      "type": "registry:component"
    }
  ]
}

This component contains a simple button. You can keep adding more components to the items array.

3. Adding Components

After creating the registry.json file, you can add components to the registry. These components can be UI elements, functions, or utilities.

Example 1: Adding a Simple Button Component

First, create the component file. You can define your component in a separate directory. For example, we will create a HelloWorld component.

// registry/new-york/hello-world/hello-world.tsx
import { Button } from "@/components/ui/button"

export function HelloWorld() {
  return 
}

Reference the component in your registry.json like this:

{
  "name": "hello-world",
  "type": "registry:block",
  "title": "Hello World",
  "description": "A simple hello world component.",
  "files": [
    {
      "path": "registry/new-york/hello-world/hello-world.tsx",
      "type": "registry:component"
    }
  ]
}

The "files" key points to the path where the component is stored, while the type helps categorize the item.

Example 2: Adding Multiple Components

You can add multiple components to the registry as well. For instance, a button and a form could be part of a UI package:

{
  "name": "ui-kit",
  "type": "registry:block",
  "title": "UI Kit",
  "description": "A collection of basic UI components.",
  "files": [
    {
      "path": "registry/ui-kit/button/button.tsx",
      "type": "registry:component"
    },
    {
      "path": "registry/ui-kit/form/form.tsx",
      "type": "registry:component"
    }
  ]
}

This modular approach allows for scalable development, enabling easy additions or updates to the registry without affecting other parts of the application.

You can learn more about registry basics in the shadcn UI docs.

Namespace System

Namespaces in shadcn help arrange components, utilities, themes, or other resources. The goal is to avoid conflicts and provide a good structure for your resources.

What is a Namespace?

A namespace groups resources under a plain identifier, usually prefixed with an '@'. With this, you can separate different types of resources, teams, or even public versus private components.

For instance:

@shadcn/button could represent a button component from shadcn's registry.
@acme/auth-utils could represent authentication utilities developed by the Acme company.

How to Configure Multiple Registries Using Namespaces

You can configure multiple registries under different namespaces, which helps organize resources by type or team:

{
  "registries": {
    "@acme-ui": "",
    "@acme-docs": "",
    "@acme-ai": "",
    "@acme-internal": {
      "url": "",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_TOKEN}"
      }
    }
  }
}

This setup allows you to:

Keep UI components, documentation, AI resources, and internal libraries separate.
Easily manage public and private resources within the same registry configuration.

You can learn more about Namespace in the shadcn UI docs.

Authentication for Private Registries

If you have private registries, shadcn offers several authentication methods to ensure that only authorized users can access them. These include Bearer Token (OAuth 2.0), API Key, Basic Authentication, and Query Parameter Authentication. Let’s look at each one in more detail.

Bearer Token (OAuth 2.0)

Bearer tokens are ideal for integrating with external APIs like GitHub or internal services that support OAuth 2.0.

You include the token in the Authorization header of the request. You typically get this token through an OAuth 2.0 flow, and it grants access to protected resources.

Here’s an example:

{
  "@github": {
    "url": "",
    "headers": {
      "Authorization": "Bearer ${GITHUB_TOKEN}"
    }
  }
}

API Key

You commonly use API keys for private NPM registries or internal APIs where a simple key is sufficient for access control.

An API key is included in the request headers, often under X-API-Key. This key is issued by the service and you should keep it confidential.

Here’s an example:

{
  "@private": {
    "url": "",
    "headers": {
      "X-API-Key": "${API_KEY}"
    }
  }
}

Basic Authentication

You’ll typically use basic authentication in legacy systems that require basic HTTP authentication.

The Authorization header contains a base64-encoded string of the format username:password. While it’s pretty easy to implement, it’s less secure than more modern methods like OAuth 2.0.

Here’s an example:

{
  "@internal": {
    "url": "",
    "headers": {
      "Authorization": "Basic ${BASE64_CREDENTIALS}"
    }
  }
}

Query Parameter Authentication

Query parameter auth is a simpler form of authentication using query parameters for APIs.

It works by passing authentication details as query parameters in the URL. While this is convenient, it’s less secure than other methods since query parameters can be exposed in logs or URLs.

Here’s an example:

{
  "@secure": {
    "url": "",
    "params": {
      "api_key": "${API_KEY}",
      "client_id": "${CLIENT_ID}",
      "signature": "${REQUEST_SIGNATURE}"
    }
  }
}

Multiple Authentication Methods

Some registries require multiple authentication methods simultaneously – for example, a combination of a Bearer token and an API key.

The request includes multiple headers and possibly query parameters to satisfy all required authentication mechanisms. This is common in enterprise environments where different layers of security are enforced.

Here’s an example:

{
  "@enterprise": {
    "url": "https://api.enterprise.com/v2/registry/{name}",
    "headers": {
      "Authorization": "Bearer ${ACCESS_TOKEN}",
      "X-API-Key": "${API_KEY}",
      "X-Workspace-Id": "${WORKSPACE_ID}"
    },
    "params": {
      "version": "latest"
    }
  }
}

You can learn more about Authentication and Security in the shadcn UI docs.

CLI Commands

The shadcn CLI lets you interact with the registry directly from the command line. With commands like add, view, search, and list, you can easily install and manage resources. Let’s look at some examples to see how this works.

Install Resources from the Registry

Use the following commands to add resources to your project:

# Install a specific component
npx shadcn@latest add @acme/button

# Install multiple components at once
npx shadcn@latest add @acme/button @lib/utils @ai/prompt

These commands fetch the specified components from the registry and integrate them into your project, ensuring all necessary dependencies are also installed.

Viewing Metadata

Before integrating a component, it's crucial to understand its structure and dependencies. The view command allows you to inspect a component's metadata:

# View a specific component
npx shadcn@latest view @acme/button

# View multiple components
npx shadcn@latest view @acme/button @lib/utils @ai/prompt

# View from a URL directly
npx shadcn@latest view https://registry.example.com/button.json

# View from a local file
npx shadcn@latest view ./local-registry/button.json

So what does the view command display?

Resource metadata: Information such as the component's name, type, and description.
Dependencies: Lists both direct and registry dependencies required by the component.
File contents: Displays the actual code that will be installed.
CSS variables and Tailwind configuration: Shows any styling configurations associated with the component.
Required environment variables: Lists any environment variables needed for the component to function correctly.

This command is invaluable for reviewing a component's details before installation, ensuring compatibility and understanding its requirements.

Searching Resources

To discover components within a registry, you can use these commands:

# Search a specific registry
npx shadcn@latest search @v0

# Search with a query
npx shadcn@latest search @acme --query "auth"

# Search multiple registries
npx shadcn@latest search @v0 @acme @lib

# Limit results
npx shadcn@latest search @v0 --limit 10 --offset 20

# List all items (alias for search)
npx shadcn@latest list @acme

They help you find components based on criteria like registry, query terms, and result limits.

Learn more about CLI Commands in the shadcn UI docs.

Dependency Resolution

The CLI automatically resolves and installs all dependencies from their respective registries.

Understanding how dependencies are resolved internally is important if you're developing registries or need to customize third-party resources.

In shadcn, components often rely on other resources from various registries. When you install a component, shadcn ensures that all its dependencies are also installed, even if they reside in different registries. This process is known as dependency resolution.

What Does It Mean to "Resolve Dependencies"?

So to be clear resolving dependencies involves identifying, fetching, and installing dependencies.

First, shadcn determines which components a resource requires to function correctly. Then it retrieves these dependent components from their respective registries. Finally, it ensures that all dependencies are installed before the main component, maintaining the correct order.

This process guarantees that when you install a component, all its prerequisites are also installed, ensuring smooth functionality.

Understanding Topological Sorting in Dependency Resolution

Topological sorting might sound complicated, but it's essentially a method of organizing tasks (or components) in a way that makes sure everything gets done in the right order.

Imagine you have a list of tasks, and some tasks depend on others to be completed first. For example, you can't make a cake without first measuring out and then mixing the ingredients. So, the tasks “measure ingredients” and "mix ingredients" need to be completed before "bake the cake."

In the context of shadcn, topological sorting works in a similar way to organizing the installation of components:

Each component (like dashboard) can depend on other components (like @shadcn/card or @acme/data-table).
Topological sorting arranges the components so that each one is installed only after the components it depends on have been installed.

Why Is Topological Sorting Important?

Topological sorting takes care of a couple key things. First, it makes sure that components are installed in the correct order. For example, if Component A depends on Component B, then Component B will be installed first, followed by Component A.

It also prevents circular dependencies. If two components depend on each other, topological sorting detects this and prevents a never-ending loop (also called a circular dependency).

Example of Dependency Resolution:

Consider the following component with its dependencies:

{
  "name": "dashboard",
  "registryDependencies": [
    "@shadcn/card",
    "@v0/chart",
    "@acme/data-table"
  ]
}

In this example, we have a component: dashboard and its dependencies: @shadcn/card, @v0/chart, and @acme/data-table.

In this case, shadcn will first identify the dependencies by recognizing that dashboard depends on @shadcn/card, @v0/chart, and @acme/data-table. Then it will fetch these components from their respective registries. Finally, it’ll install @shadcn/card, @v0/chart, and @acme/data-table first, before installing dashboard, ensuring all prerequisites are met.

You can learn more about Dependency Resolution in the shadcn UI docs.

Error Handling

shadcn’s CLI is equipped to handle several types of errors. Here are some common scenarios and how to resolve them:

Common Errors

1. Unknown Registry

This error occurs when the registry isn’t defined in the configuration.

Here’s an example:

Error: Unknown registry "@non-existent"

Solution: To fix this, just add the registry in the registries section of your configuration.

2. Missing Environment Variables

If your registry requires certain environment variables that are not set, you'll get an error.

Here’s an example:

Registry "@private" requires REGISTRY_TOKEN

Solution: To fix this, just add the required environment variables to .env or .env.local.

3. 404 Not Found

The resource may not exist or the URL could be incorrect.

Here’s an example:

Error: The resource was not found at //api.company.com/button.json>

4. Authentication Failures (401/403)

If you’re not authorized to access a resource, you’ll see 401 or 403 errors.

To fix this, make sure your tokens, API keys, or credentials are valid.

You can learn more about Error Handling in the shadcn UI docs.

Conclusion

The shadcn registry system provides a good, modular solution for managing and sharing components or utilities across projects. If you’re looking to explore practical implementations, platforms like shadcn/studio which showcase how you can leverage shadcn components to build sleek, modern UI solutions with minimal setup.

With its structured approach to dependencies, flexible namespaces, good authentication, and CLI commands, registries enable teams to share secure resources and customize them along the way.

I have prepared this article with the help of Pruthvi Prajapati, a front-end developer with 3 years of experience.

How to Make a Dropdown Menu with shadcn/ui

Ajay Kalal — Thu, 17 Jul 2025 21:02:46 +0000

Dropdown menus are little pop-up menus that help you show more options without cluttering your screen. They’re super helpful in websites and apps.

In this guide, you’ll learn how to build a dropdown menu using shadcn/ui. It’s a tool that works well with Tailwind CSS and Radix UI to help you make nice-looking, easy-to-use menus.

What is shadcn/ui?
Why Use shadcn/ui for Dropdowns?
Let’s Build a Dropdown Step-by-Step
Real-World Use Case: Country Dropdown with Flags
Final Thoughts

💡 Prerequisites

Before we start, make sure you have:

Basic knowledge of React and JavaScript
Node.js and a package manager like npm, pnpm, or yarn are installed
Familiarity with Tailwind CSS is a bonus, but not required

We’ll walk through everything step by step, so don’t worry if you’re not an expert yet.

What is shadcn/ui?

shadcn/ui is a group of tools (called components) that help you build parts of a website, like buttons, modals, and dropdowns. It’s built with Radix UI and styled using Tailwind CSS. It’s perfect if you’re using React or Next.js.

With shadcn/ui, you don’t get just styled components, you get full control over how everything works and looks. That makes it perfect for teams that want consistency in design without giving up flexibility.

Why Use shadcn/ui for Dropdowns?

Dropdown menus are a great use case for shadcn/ui because:

It’s easy to use with keyboard and screen readers
You can create custom looks using Tailwind CSS
You control how it works and looks
It works great in real websites and apps
It integrates well with modern React workflows

Step 1: Start a New Project with shadcn/ui

You don’t need to set up React, Next.js, or Tailwind manually. Just run this command:

pnpm dlx shadcn@latest init

This will automatically create a new Next.js app with Tailwind CSS and shadcn/ui preconfigured.

Tip: You can also use npx instead of pnpm dlx if you prefer:

npx shadcn@latest init

After your project is ready, add the dropdown component using:

npx shadcn@latest add dropdown-menu

This will pull in all the necessary components to create a dropdown menu.

Step 3: Import What You Need

In your React file, import the full dropdown module so you can access all its features:

import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuGroup,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuPortal,
} from "@/components/ui/dropdown-menu"

Here’s a basic dropdown example:

export function ProfileMenu() {
  return (
    
      
        
      
      
        My Account
        
        Profile
        Settings
        Log out
      
    
  )
}

This is just the start. You can add groups, submenus, and keyboard shortcuts for power users.

Step 5: Make It Look Better

Use Tailwind CSS to style your dropdown, and hover effects like this:


        
          
        
        
          
            My Account
          
          
          
            Profile
          
          
            Settings
          
          Step 6: Make It Work on All Screens
Want your dropdown to be responsive? Use Tailwind’s responsive classes:


You can also dynamically position the dropdown using Radix's built-in portal support.
Step 7: Add Cool Icons

Install Lucide icons:
npm install lucide-react

Then use them in your menu:
import { User, Settings, LogOut } from "lucide-react"


   Profile


Icons help users scan options quickly – a great touch for UX.
Step 8: It’s Already Accessible!
shadcn/ui (thanks to Radix UI) makes your dropdown menu:

Keyboard friendly

Screen-reader ready

Following best web practices


You don’t need to configure accessibility – it just works :)
Real-World Use Case: Country Dropdown with Flags
Looking for a more advanced dropdown? Here’s an amazing example that includes search, flag icons, and grouping:

👉 shadcn-country-dropdown.vercel.app
It’s open-source and a great place to see what’s possible with shadcn/ui.
Final Thoughts
Using shadcn/ui to create a dropdown menu is fast, simple, and powerful. You get great styling, accessibility, and full control over how things look and work. Whether you’re just starting out or building for production, this is a solid tool to use.
Dropdowns are just the beginning. shadcn/ui offers a whole library of headless components for building modern UIs.
I hope you found this article helpful! If you're building a SaaS product or any web app that involves user interaction or conversion, consider enhancing user trust with real-time notifications like modal pop-ups, sales pop up, etc.



 Mastering Shadcn UI Components 
Beau Carnes — Fri, 28 Jun 2024 16:25:33 +0000
 We just published a course on the freeCodeCamp.org YouTube channel that will help you master Shadcn. This comprehensive course dives deep into the versatile world of Shadcn, a powerful toolset for building modern web applications with customizable and reusable components. Mathew from CodeByDesign designed this course.
What is Shadcn?
Shadcn is not your typical component library. Instead of installing it as a dependency through npm, Shadcn offers a collection of beautifully designed, accessible, and customizable React components that you can copy and paste directly into your project. This unique approach allows developers to have complete control over their components, enabling greater customization and integration flexibility.
The Shadcn components are designed to be easily integrated into any React or Next.js project. They come with built-in styling options and support theming through CSS variables or Tailwind CSS utility classes, making it simple to maintain a consistent look and feel across your application.
This course covers all the main UI components provided by Shadcn, offering a thorough introduction and practical examples to help you get started quickly.
Why Learn Shadcn?
Shadcn offers a flexible and efficient way to build modern web applications with React and Next.js. By mastering Shadcn, you can:

Speed up your development process by reusing high-quality, pre-built components.

Maintain complete control over your component styling and behavior.

Ensure your application is accessible and user-friendly with components designed with accessibility in mind.


Whether you are a beginner looking to get started with React UI components or an experienced developer aiming to enhance your toolkit, this course provides valuable insights and practical knowledge to help you succeed. Watch the course on the freeCodeCamp.org YouTube channel (3-hour watch).

shadcn - freeCodeCamp.org

How to Build a Shadcn Sheet Component in React: Cart and Filter Panel Examples

Table of Contents

Prerequisites

What You'll Build

How to Set Up the CLI Registry

How to Build the Shopping Cart Sheet (sheet-03)

What the Cart Sheet Does

How to Install the Cart Sheet

The Component Code

1. Derived totals instead of tracked state

2. Removing an item is just zeroing its quantity

3. render prop instead of asChild

4. Fixed header and footer, scrollable middle

Live Preview:

How to Build the Filter Panel Sheet (sheet-04)

What the Filter Sheet Does

How to Install the Filter Sheet

The Component Code

1. Use a separate state for each filter type

2. activeCount is computed, not tracked

3. "Apply Filters" closes the panel, "Clear All" doesn't

4. Toggling a category with .filter() and spread

Live Preview:

Quick Reference Table

Key Concepts for Using Shadcn Sheet

Conclusion

Resources

How to Build Production-Ready Card Components with shadcn/ui

Table of Contents

Prerequisites

Why shadcn/ui?

What is Shadcn Space?

What You'll Build

How to Set Up the CLI Registry

How to Build the Preview Card (card-02)

What the Preview Card Does

How to Install the Preview Card

The Component Code

Serenity Residential Home

1. Group hover behavior

2. Overflow clipping on image zoom

3. Logical border properties in the amenity row

Live Preview:

How to Build the Analytics Card (card-05)

What the Analytics Card Does

How to Install the Analytics Card

The Component Code

1. Optional props with a default dataset

2. Conditional badge colors with cn()

3. Separators only between metrics, not after the last one

4. Absolute-positioned decorative image

Live Preview:

How to Build the Statistics Card (card-06)

What the Statistics Card Does

How to Install the Statistics Card

The Component Code

{item.title}

{item.subtitle}

1. Data-driven layout with an array

2. Responsive column widths

3. Removing the last border with last:

4. Why "use client" is needed here

Live Preview:

How to Build the Ecommerce Product Variant Card (card-17)

What the Ecommerce Product Variant Card Does

How to Install the Product Variant Card

The Component Code

Nike

1. Named group hover scopes

2. CSS ripple animation on the Buy Now button

3. Ordinal suffix logic for the delivery date

4. suppressHydrationWarning on the delivery date span

Live Preview:

Quick Reference Table

Key Concepts Recap

Tailwind Group Hover

The cn() Utility

last: Tailwind Variant

CSS Logical Properties

3. `render` prop instead of `asChild`

2. `activeCount` is computed, not tracked

4. Toggling a category with `.filter()` and spread

2. Conditional badge colors with `cn()`

3. Removing the last border with `last:`

4. Why `"use client"` is needed here

4. `suppressHydrationWarning` on the delivery date span

The `cn()` Utility

`last:` Tailwind Variant

`"use client"` in Next.js App Router

`suppressHydrationWarning`

`scale: 1 - idx * 0.1`

`top: hovering ? idx * -15 : 0`

`zIndex: -idx`

`opacity: idx < 3 ? 1 - idx * 0.1 : 0`

`animate={{ y: idx === 0 ? [0, 40, 0] : 0 }}`

`layoutId={tab.value}`