That means collecting a business type, pulling in registration documents, and showing the user where their verification stands, all without making onboarding feel like a customs form.

This article breaks down a working three step KYC (Know Your Customer) flow built with Shadcn UI: a stepper for progress, a radio group for account type, a file upload zone for documents, and an alert for verification status. You'll see the actual component code, not a simplified stand-in, along with the reasoning behind each decision.

You can try the finished flow at onboarding-kyc-flow.vercel.app. Click through it once before reading on, as it makes the code below easier to follow. And it also comes in dark and light mode.

Table of Contents

• Prerequisites

• What You're Building

• Project Structure

• Radix UI vs Base UI: Which Primitives this Flow Uses

• Scaffolding the Flow with v0 and an MCP Server

• Step 1: Account Type with a Radio Group

• Step 2: Document Upload with Drag and Drop

• Step 3: Verification Status with an Alert

• Adding a Stepper to the Flow

• Small Details that Make it Feel Finished

• Accessibility notes

• Key Concepts Recap

• Conclusion

• Resources

Prerequisites

Before working through this flow, you should be comfortable with React function components and hooks, specifically useState, useRef, and useEffect.

You should have:

• A Next.js project with the App Router and shadcn/ui already initialized, since this article doesn't cover that initial setup.

• A v0 account is optional. You can also use Bolt or Lovable, which support the same shadcn MCP prompt feature.

What You're Building

The flow has three steps:

1. Account type: The user picks Startup, Enterprise, or Government. This decision drives the rest of the experience. It's shown back to the user as a confirmation line, and would typically decide which workspace defaults get applied.

2. Document upload: The user drags in a business registration document, a tax return, or a company registry export, in PDF or CSV format.

3. Verification status: The user sees a live status: checking in progress, then either verified or an issue that needs attention.

Project Structure

The project is a standard Next.js app with shadcn/ui already initialized. Here's the top-level layout:

onboarding-kyc-flow/
├── .vercel/
├── app/
├── components/
├── lib/
├── public/
├── .env.development.local
├── .gitignore
├── components.json
├── next-env.d.ts
├── next.config.mjs
├── package.json
├── pnpm-lock.yaml
├── postcss.config.mjs
├── tsconfig.json
└── tsconfig.tsbuildinfo

components.json is the file the shadcn CLI reads to know where your components live and which style and primitives you're using. components/ holds the shared UI pieces (Alert, Badge, Button, Card, Progress, RadioGroup, Separator) that the flow is built from. lib/utils.ts provides the cn helper used throughout the flow to combine conditional class names. app/ holds the page itself, shown in full below.

Radix UI vs Base UI: Which Primitives this Flow Uses

Shadcn components aren't tied to one underlying primitive library. Most of the ecosystem defaults to Radix UI, but Base UI has become a solid alternative, and it's what this flow is built on.

The underlying primitive library can affect how a component behaves and how you work with it in your project. If you're pulling components from a set like Shadcn UI, check which primitive library it targets before mixing components from different sources.

Mixing Radix-based and Base UI-based components generally works, but it means using two different unstyled primitive libraries in the same project. You can compare Radix UI and Base UI here.

Scaffolding the Flow with v0 and an MCP Server

An MCP (Model Context Protocol) server exposes a component library to an AI coding assistant as a set of callable tools. Instead of the assistant guessing at component names and props from training data, it queries the server for the real, current API.

This matters here specifically, since there are now several shadcn-style component sets with similar names and different props.

The Shadcn Components library publishes an MCP server for its free set, connected to v0 by following its getting started guide. The video below covers the connection step by step. The same generated output can also be copied into Lovable or Bolt through their copy prompt feature, so the workflow isn't locked to one AI builder.

The prompt used to scaffold this flow looked like this:

Create an Enterprise SaaS Onboarding & KYC Flow. Use free components of the shadcn space MCP server: shadcn alert, shadcn radio group, shadcn stepper, shadcn file upload. Only use free components, not pro ones, and list which free component was used for each part.

Step 1: Account Type (stepper) - radio group for Startup, Enterprise, or Government

Step 2: Upload Documents (stepper) - file upload for a business registration document

Step 3: Verification (stepper) - alert showing verification status

This produces a working first draft fast. What follows is the result after cleaning that draft up: real state management, real validation, and states that a generated draft tends to skip.

Step 1: Account Type with a Radio Group

Account type is the first decision in the flow because it's the one most likely to affect what comes after it. Asking it early keeps the rest of the flow feeling relevant to the choice the user just made.

const tiers: { id: Tier; name: string; description: string; tag: string }[] = [
  { id: 'startup', name: 'Startup', description: 'For teams building and scaling fast', tag: 'Up to 25 seats' },
  { id: 'enterprise', name: 'Enterprise', description: 'For established teams with advanced needs', tag: 'Unlimited seats' },
  { id: 'government', name: 'Government', description: 'For public sector and regulated teams', tag: 'FedRAMP-ready' },
]

<RadioGroup value={tier} onValueChange={(value) => setTier(value as Tier)} className="grid gap-3">
  <fieldset className="contents">
    <legend className="sr-only">Account type</legend>
    {tiers.map((item) => (
      <label
        key={item.id}
        htmlFor={item.id}
        className={cn(
          'flex cursor-pointer items-start gap-4 rounded-xl border p-4 transition-colors hover:border-primary/50',
          tier === item.id && 'border-primary bg-primary/5'
        )}
      >
        <RadioGroupItem value={item.id} id={item.id} className="mt-0.5" />
        <span className="flex flex-1 flex-col gap-1">
          <span className="flex flex-wrap items-center gap-2 text-sm font-semibold">
            {item.name}
            {item.id === 'enterprise' && <Badge variant="secondary">Recommended</Badge>}
          </span>
          <span className="text-sm text-muted-foreground">{item.description}</span>
          <span className="mt-1 font-mono text-[11px] uppercase tracking-wide text-muted-foreground">{item.tag}</span>
        </span>
      </label>
    ))}
  </fieldset>
</RadioGroup>

Two things worth noticing here. The tier data lives in a plain array outside the component, so adding a fourth tier later is a one-line change, not a markup change. And the fieldset with a visually hidden (sr-only) legend groups the three options as one related choice for screen readers. Sighted users never see it, since the card title above already states "Choose your account type" visually.

This step uses a shadcn radio group rather than a select or checkboxes, since account type is a single, mutually exclusive choice, and a radio group is the only one of the three that makes both the options and the current selection visible at a glance.

Live Preview:

Step 2: Document Upload with Drag and Drop

The upload zone needs to handle three states cleanly: nothing selected yet, a file selected and ready, and a rejected file with a specific reason why.

function FileUpload({ file, onFile, onRemove, error }: {
  file: File | null
  onFile: (file: File) => void
  onRemove: () => void
  error: string
}) {
  const inputRef = useRef<HTMLInputElement>(null)
  const [dragging, setDragging] = useState(false)

  const accept = (candidate: File) => {
    if (candidate.type !== 'application/pdf' && candidate.type !== 'text/csv' && !candidate.name.toLowerCase().endsWith('.csv')) {
      return 'Upload a PDF or CSV file only.'
    }
    if (candidate.size > 10 * 1024 * 1024) {
      return 'Files must be smaller than 10 MB.'
    }
    onFile(candidate)
    return ''
  }

  return (
    <div className="flex flex-col gap-3">
      {!file ? (
        <button
          type="button"
          className={cn(
            'group flex min-h-44 flex-col items-center justify-center rounded-xl border border-dashed bg-muted/30 px-6 text-center transition-colors hover:border-primary hover:bg-primary/5',
            dragging && 'border-primary bg-primary/10'
          )}
          onClick={() => inputRef.current?.click()}
          onDragOver={(event) => { event.preventDefault(); setDragging(true) }}
          onDragLeave={() => setDragging(false)}
          onDrop={(event) => {
            event.preventDefault()
            setDragging(false)
            const dropped = event.dataTransfer.files[0]
            if (dropped) accept(dropped)
          }}
        >
          <input
            ref={inputRef}
            className="sr-only"
            type="file"
            accept=".pdf,.csv,application/pdf,text/csv"
            onChange={(event) => {
              const selected = event.target.files?.[0]
              if (selected) accept(selected)
            }}
          />
          <span className="mb-3 flex size-11 items-center justify-center rounded-lg border bg-background text-primary shadow-sm">
            <UploadCloud className="size-5" aria-hidden="true" />
          </span>
          <span className="text-sm font-semibold">Drop your business document here</span>
          <span className="mt-1 text-xs text-muted-foreground">or click to browse · PDF or CSV · max 10 MB</span>
        </button>
      ) : (
        <div className="flex items-center gap-3 rounded-xl border bg-muted/30 p-4">
          <span className="flex size-10 items-center justify-center rounded-lg bg-primary/10 text-primary">
            <FileText className="size-5" aria-hidden="true" />
          </span>
          <div className="min-w-0 flex-1">
            <p className="truncate text-sm font-semibold">{file.name}</p>
            <p className="text-xs text-muted-foreground">{(file.size / 1024 / 1024).toFixed(2)} MB · Ready to verify</p>
          </div>
          <Badge variant="secondary" className="hidden sm:inline-flex">Uploaded</Badge>
          <Button type="button" variant="ghost" size="icon-sm" aria-label="Remove file" onClick={onRemove}>
            <X className="size-4" aria-hidden="true" />
          </Button>
        </div>
      )}
      {error && (
        <Alert variant="destructive">
          <AlertCircle className="size-4" aria-hidden="true" />
          <AlertTitle>Unsupported document</AlertTitle>
          <AlertDescription>{error}</AlertDescription>
        </Alert>
      )}
    </div>
  )
}

The accept function is the whole validation layer, and it runs from two different places: the change handler on the hidden file input, and the drop handler on the drag zone.

Both paths call the same function, so a file dragged in gets the same validation checks as a file selected by clicking browse. It ensures that only PDF or CSV files are allowed, regardless of how the file is added.

This is where shadcn file upload earns its place over a plain <input type="file">: the drag zone, the selected state, and the rejected state are all handled as one component instead of three separate pieces wired together by hand.

Live Preview:

Step 3: Verification Status with an Alert

Verification isn't instant, so the interface needs to say clearly what's happening and what happens next, rather than showing a spinner with no explanation.

{verified ? (
  <Alert className="border-primary/30 bg-primary/5">
    <CheckCircle2 className="size-4 text-primary" aria-hidden="true" />
    <AlertTitle>Verification complete</AlertTitle>
    <AlertDescription>
      Your {selectedTier.name.toLowerCase()} workspace is ready to configure.
    </AlertDescription>
  </Alert>
) : (
  <>
    <Alert>
      <AlertCircle className="size-4" aria-hidden="true" />
      <AlertTitle>Verification in progress</AlertTitle>
      <AlertDescription>
        This usually takes a few moments. You can keep this tab open while we finish.
      </AlertDescription>
    </Alert>
    <div className="flex flex-col gap-3">
      <div className="flex items-center justify-between text-sm">
        <span className="font-medium">Checking business registry</span>
        <span className="font-mono text-xs text-muted-foreground">{checking ? '68%' : '100%'}</span>
      </div>
      <Progress value={checking ? 68 : 100} />
      <div className="flex items-center gap-2 text-xs text-muted-foreground">
        <Building2 className="size-3.5" aria-hidden="true" /> Matching company details and tax identifiers
      </div>
    </div>
  </>
)}

Pairing the shadcn alert with a progress bar does two jobs at once: the alert states the current status in words, while the progress bar gives a rough sense of how much is left, without promising a specific time. Neither one alone tells the full story, the alert alone feels static, and a progress bar alone doesn't explain what's actually being checked.

Worth adding here, and easy to skip when a demo only shows the success path: a mismatch state, where the tax ID on the document doesn't match the company registry, deserves its own alert with a clear next step: contact support or re-upload a corrected document. It's not shown above, since the flow currently resolves to either checking or verified, but it's the state a production version of this flow would hit the most.

Live Preview:

Adding a Stepper to the Flow

The stepper is the visual anchor of the whole flow. It's the piece that tells the user how much is left before the checking and account-type-selecting are done.

function Stepper({ current }: { current: Step }) {
  return (
    <nav
      aria-label="Onboarding progress"
      className="grid grid-cols-[minmax(0,1fr)_minmax(2rem,5rem)_minmax(0,1fr)_minmax(2rem,5rem)_minmax(0,1fr)] items-start gap-0"
    >
      {steps.map((step, index) => (
        <div key={step.number} className="contents">
          <div className="flex min-w-0 flex-col items-center text-center">
            <div
              className={cn(
                'flex size-9 items-center justify-center rounded-full border text-sm font-semibold transition-colors',
                current > step.number
                  ? 'border-primary bg-primary text-primary-foreground'
                  : current === step.number
                  ? 'border-primary bg-primary/10 text-primary'
                  : 'border-border bg-background text-muted-foreground'
              )}
              aria-current={current === step.number ? 'step' : undefined}
            >
              {current > step.number ? <Check className="size-4" aria-hidden="true" /> : step.number}
            </div>
            <div className="mt-2 min-w-0">
              <p className={cn('truncate text-sm font-semibold', current >= step.number ? 'text-foreground' : 'text-muted-foreground')}>
                {step.label}
              </p>
              <p className="mt-1 hidden text-xs leading-5 text-muted-foreground sm:block">{step.caption}</p>
            </div>
          </div>
          {index < steps.length - 1 && (
            <div className={cn('mt-4 h-px w-full', current > step.number ? 'bg-primary' : 'bg-border')} />
          )}
        </div>
      ))}
    </nav>
  )
}

The current > step.number check keeps the entire stepper in sync with a single comparison. It determines the circle’s fill color, decides when the step number should be replaced by a checkmark, and controls whether the connecting line to the next step is filled.

This is important because the stepper only needs one piece of state, step, from the parent component. It doesn’t need to know why the user is on step 2, it only needs to know which step is currently active and update its visual state accordingly.

The "continue" logic that actually advances step lives outside the stepper itself:

const continueStep = () => {
  if (step === 1) setStep(2)
  else if (step === 2 && file) {
    setStep(3)
    setChecking(true)
    window.setTimeout(() => {
      setChecking(false)
      setVerified(true)
    }, 1400)
  }
}

Keeping this in the page component, not inside the shadcn stepper itself, is what keeps the stepper reusable. It only renders progress. Whether the user is allowed to move forward, a file is required on step 2, or whether nothing is required on step 1, is a decision for the flow around it to make.

Small Details that Make it Feel Finished

A few things in this build are easy to skip but change how the flow feels in practice:

• A dark mode toggle in the header, wired to a darkMode state that toggles a class on document.documentElement. It's small, but it means the flow doesn't fight a user's system theme preference.

• A security note in the sidebar, stating documents are encrypted and deleted after verification. This is copy, not code, but it answers the question a corporate user is quietest about and most worried by: what happens to the file after I upload it.

• A "Selected" confirmation line under the radio group, restating the chosen tier in plain text. A small detail, but it removes any doubt about what was actually selected before moving on.

If you're looking to wrap a flow like this inside a full application shell, with navigation and a dashboard around it, the Shadcn Dashboard starter uses the same component set. It's a reasonable base to extend from rather than building a shell from scratch.

Live Preview:

https://onboarding-kyc-flow.vercel.app/

This project is open source, and you can easily download the zip and if you like. Please consider giving it a star.

• Github Repo

Accessibility notes

• The stepper's nav element has an aria-label, and the current step carries aria-current="step", so assistive technology can identify progress without relying on visual position alone.

• The radio group sits inside a fieldset with a screen-reader-only legend, grouping the three account types as one decision.

• Icons throughout (Check, AlertCircle, UploadCloud, and so on) carry aria-hidden="true", since they're decorative next to text that already states the same information. This stops screen readers from announcing redundant icon labels.

• The remove-file button has an explicit aria-label, since its visible content is an icon only, with no text.

Key Concepts Recap

• Account type comes first because it's the one decision most likely to affect the rest of the flow, and it's kept in state at the page level, not inside the radio group itself.

• File validation runs in a shared function used by both the drag-and-drop path and the click-to-browse path, so both paths apply the same PDF/CSV validation.

• Verification status is communicated with both words (the alert) and a rough sense of progress (the progress bar), since either one alone leaves out part of the picture.

• The stepper is a pure display component driven by a single step value from its parent. The logic for whether the user can advance lives outside it, not inside it.

• Small, non-technical details (like a security note, a confirmation line, or a theme toggle) do as much for how finished a flow feels as any of the four core components.

Conclusion

None of the four components in this flow are complicated individually. What makes a KYC flow work is the decisions around them: which choice comes first, where validation actually runs, and how honestly the interface talks to the user while something outside their control is being checked.

Whether the first draft comes from typing every line by hand or from scaffolding it with an MCP server and v0, that's the part worth spending time getting right before it ships.

Resources

• Shadcn Components, the free component set used in this flow

• ShadcnSpace, the base library these components extend

• MCP server walkthrough

• MDN: ARIA current attribute

• Model Context Protocol specification

So I built and open-sourced a complete SaaS landing page template called ChatDeck. It runs on Next.js 16, React 19, shadcn/ui with the new base-nova style, Tailwind CSS v4, and TypeScript. The full source is on GitHub under the MIT license. I built and open-sourced this template, and everything here comes from decisions made during that process.

Building it forced me to make real decisions on a stack that moved significantly in the past 12 months. This article is about those decisions: what worked, what didn't, and what I'd do differently if I started today.

Prerequisites: This article assumes you're comfortable with React and TypeScript. Some familiarity with the Next.js App Router is helpful but not required. Each lesson is explained from first principles.

Table of Contents

• The Stack Choices and Why They Matter

• Getting Started

• Project Structure

• Lesson 1: shadcn/ui's Newbase-novaStyle Changes What "Accessible" Means

• Lesson 2: Tailwind CSS v4 Requires a Mental Model Shift

• Lesson 3: OKLCH Colors Make Dark Mode Predictable

• Lesson 4: Page Architecture — Flat Beats Clever

• Lesson 5: Staggered Animations Without Managing Individual Delays

• Lesson 6: CSS-Only Infinite Scroll — No Library Needed

• Lesson 7: CSS Subgrid Solves Pricing Card Alignment Natively

• Lesson 8: Inline SVGs Beat Image Libraries for Simple Logos

• What I'd Do Differently

• Summary

The Stack Choices and Why They Matter

Before getting into the code, here's what the template runs on. Each choice was deliberate — none of these are defaults you get from create-next-app.

The most interesting decisions in this list are the ones that reflect how the ecosystem changed in the past year: Base UI replacing Radix inside shadcn/ui, and Tailwind v4's shift to CSS-first configuration. The lessons below walk through each of these in detail, starting with the choices that had the biggest impact on how the code is actually written.

Getting Started

Before diving into the lessons, here's how to get the project running locally. Having it open alongside this article makes the code examples easier to follow.

git clone https://github.com/ShadcnDeck/chatdeck-shadcn-saas-landing-page-template.git
cd chatdeck-shadcn-saas-landing-page-template
pnpm install
pnpm dev

Open http://localhost:3000 and you'll see the full landing page running locally.

All section content lives as plain TypeScript arrays inside each Block component. To change the features, edit the features array in FeatureSection.tsx. To change pricing tiers, edit the plans array in PricingSection.tsx. No CMS, no config files — just TypeScript objects.

To customize colors, update the OKLCH values in app/globals.css under the :root block. Change --primary and every button, link, and accent color updates across the entire template.

Deploy to Vercel with a single vercel command or by pushing to GitHub and connecting the repo. Next.js is detected automatically.

Project Structure

Here's the full directory layout before we go through each part of it:

chatdeck/
├── app/
│   ├── globals.css         # Theme tokens + custom animations (Tailwind v4 @theme)
│   ├── layout.tsx          # Root layout — Navbar, Footer, fonts
│   └── page.tsx            # Section imports — 16 lines
├── components/
│   ├── Blocks/             # Page sections (Hero, Features, Pricing, etc.)
│   ├── ui/                 # shadcn/ui components — base-nova style
│   └── navbar.tsx          # Scroll-aware sticky navbar
└── lib/
    └── utils.ts            # cn() helper (clsx + tailwind-merge)

The key separation is Blocks/ vs ui/. The ui/ folder holds primitive components — Button, Badge, Accordion — that come from shadcn/ui and rarely change. The Blocks/ folder holds page-level sections that are specific to this template and change often. When you're customising, you mostly work in Blocks/. When you upgrade shadcn/ui components, you touch ui/.

The lessons below go through specific files in this structure piece by piece: components.json and ui/accordion.tsx in Lesson 1, app/globals.css in Lessons 2 and 3, app/page.tsx in Lesson 4, and the individual Block components in Lessons 5 through 8.

Lesson 1: shadcn/ui's New base-nova Style Changes What "Accessible" Means

If you've used shadcn/ui before, you know the default setup uses Radix UI primitives, headless components that handle focus management, keyboard navigation, and ARIA attributes. Radix has been the default for years.

But shadcn/ui introduced a new style in 2025 called base-nova, which replaces Radix with Base UI, the headless primitive library from MUI.

Based on shadcn's public direction and the components released through 2025, base-nova appears to be the intended default going forward (though shadcn hasn't yet deprecated the Radix style).

In the project's components.json:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-nova",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "iconLibrary": "lucide"
}

The "style": "base-nova" line means every component the shadcn/ui CLI installs wraps Base UI primitives instead of Radix. To understand what this changes in practice, here's what the same Accordion trigger component looks like in the older Radix-based default style:

// Radix-based default style (the old way)
import * as AccordionPrimitive from "@radix-ui/react-accordion"

const AccordionTrigger = React.forwardRef<
  React.ElementRef<typeof AccordionPrimitive.Trigger>,
  React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Trigger>
>(({ className, children, ...props }, ref) => {
  const [isOpen, setIsOpen] = React.useState(false)

  return (
    <AccordionPrimitive.Header className="flex">
      <AccordionPrimitive.Trigger
        ref={ref}
        className={cn("flex flex-1 items-center justify-between ...", className)}
        onClick={() => setIsOpen(!isOpen)}
        {...props}
      >
        {children}
        <ChevronDownIcon
          className={cn(
            "h-4 w-4 shrink-0 transition-transform duration-200",
            isOpen ? "hidden" : "block"
          )}
        />
        <ChevronUpIcon
          className={cn(
            "h-4 w-4 shrink-0 transition-transform duration-200",
            isOpen ? "block" : "hidden"
          )}
        />
      </AccordionPrimitive.Trigger>
    </AccordionPrimitive.Header>
  )
})

Notice the useState(false) tracking whether the accordion is open, and the onClick handler that toggles it. This means the component has to manually keep its own isOpen state in sync with what Radix internally knows about the open/closed state.

Now here's the same component using the base-nova style with Base UI:

// components/ui/accordion.tsx — base-nova style (the new way)
import { Accordion as AccordionPrimitive } from "@base-ui/react/accordion"

function AccordionTrigger({ className, children, ...props }: AccordionPrimitive.Trigger.Props) {
  return (
    <AccordionPrimitive.Header className="flex">
      <AccordionPrimitive.Trigger
        data-slot="accordion-trigger"
        className={cn(
          "group/accordion-trigger relative flex flex-1 items-start ...",
          className
        )}
        {...props}
      >
        {children}
        <ChevronDownIcon
          className="pointer-events-none shrink-0 group-aria-expanded/accordion-trigger:hidden"
        />
        <ChevronUpIcon
          className="pointer-events-none hidden shrink-0 group-aria-expanded/accordion-trigger:inline"
        />
      </AccordionPrimitive.Trigger>
    </AccordionPrimitive.Header>
  )
}

No useState. No onClick. No isOpen variable. The chevron visibility is controlled entirely by group-aria-expanded/accordion-trigger:hidden — a Tailwind class that reads the aria-expanded attribute Base UI sets automatically on the trigger element.

The lesson here: in the Radix version, you have two parallel systems: the component's own isOpen state, and the ARIA attributes that the library manages separately for screen readers. These can drift out of sync — for example, if the accordion closes via keyboard navigation, the ARIA state updates correctly but your isOpen state doesn't unless you wire up the right callbacks. In the Base UI version, there is only one system. ARIA state IS the state. Tailwind reads it directly. There's nothing to keep in sync and nothing that can drift.

Lesson: use the primitive library's ARIA attributes as your source of truth for visual state. If your headless component library already sets aria-expanded, aria-selected, or aria-checked, Tailwind can respond to those directly with aria-* variant classes — no parallel JavaScript state needed.

So when you install shadcn/ui today, choose base-nova over the default Radix style. You get tighter Base UI integration, a smaller peer dependency footprint, and components that are more aligned with where the ecosystem is moving.

Lesson 2: Tailwind CSS v4 Requires a Mental Model Shift

Tailwind CSS v4 moves primary theme configuration out of the JavaScript config file and into CSS. This sounds small. In practice, it changes how you think about the entire theming system.

In Tailwind v3, you'd extend the theme in tailwind.config.js:

// OLD — tailwind.config.js (v3)
module.exports = {
  theme: {
    extend: {
      animation: {
        marquee: "marquee 40s linear infinite",
      },
      keyframes: {
        marquee: {
          from: { transform: "translateX(0)" },
          to: { transform: "translateX(calc(-100% - var(--gap)))" },
        },
      },
    },
  },
}

In Tailwind v4, that same configuration lives in your CSS file instead:

/* app/globals.css — Tailwind v4 */
@import "tailwindcss";

@theme inline {
  --animate-marquee: marquee var(--duration) infinite linear;
  --animate-marquee-vertical: marquee-vertical var(--duration) linear infinite;

  @keyframes marquee {
    from { transform: translateX(0); }
    to   { transform: translateX(calc(-100% - var(--gap))); }
  }

  --radius-2xl: calc(var(--radius) * 1.8);
  --radius-3xl: calc(var(--radius) * 2.2);
  --radius-4xl: calc(var(--radius) * 2.6);
}

The @theme inline block extends Tailwind's design token system. Define --animate-marquee here and you can use className="animate-marquee" anywhere in your components. Tailwind generates the utility class automatically from the CSS variable.

Custom animations, radius scales, and color tokens all live in CSS now. The benefit is that CSS is where styles belong. The config file was always an indirection layer between "what I want my design system to look like" and "where that actually lives." Tailwind v4 removes the indirection.

The friction: if you start a Tailwind v4 project with a v3 mental model, you'll spend time looking for theme config in the wrong place. Read the v4 migration guide before you start, not after you're confused.

Lesson: move your mental model of "theme config" from JavaScript to CSS. In Tailwind v4, if you want a custom animation, a new radius scale, or a color token, define it in @theme inline inside globals.css. That's where it belongs, and that's where every developer on your team will find it.

Lesson 3: OKLCH Colors Make Dark Mode Predictable

The template uses OKLCH color values throughout, not hex or HSL:

:root {
  --background: oklch(1 0 0);        /* white */
  --foreground: oklch(0.145 0 0);    /* near-black */
  --primary: oklch(0.205 0 0);
  --border: oklch(0.922 0 0);
}

.dark {
  --background: oklch(0.145 0 0);    /* near-black */
  --foreground: oklch(0.985 0 0);    /* near-white */
  --primary: oklch(0.922 0 0);
  --border: oklch(1 0 0 / 10%);      /* white at 10% opacity */
}

OKLCH is a perceptually uniform color space. When you increase the lightness value in OKLCH, the color actually looks lighter to human eyes, consistently. Hex and HSL don't guarantee this. You can increase the L in HSL and get a color that looks the same or even darker depending on the hue.

For dark mode specifically, this matters because you're inverting a whole color system. With HSL, you'll often end up manually tweaking individual color values until contrast ratios look right. With OKLCH, increasing or decreasing the lightness value gives you predictable results across all your tokens.

The dark mode switch itself is zero JavaScript. Adding class="dark" to the <html> element swaps every CSS variable. Tailwind reads the updated variables and re-renders every component. There's no context provider and no useTheme hook needed for the CSS layer — just a class toggle on the root element.

Lesson: swap your color tokens to OKLCH. When defining dark mode values, adjust the first OKLCH parameter (lightness) and the result will look predictably lighter or darker. With hex or HSL you're often guessing; with OKLCH you're reasoning.

Lesson 4: Page Architecture — Flat Beats Clever

The main page file is 16 lines:

// app/page.tsx
import Hero from "@/components/Blocks/Hero";
import { LogoCarousel } from "@/components/Blocks/LogoCarousel";
import { FeatureSection } from "@/components/Blocks/FeatureSection";
import { TeamSection } from "@/components/Blocks/TeamSection";
import { TestimonialSection } from "@/components/Blocks/TestimonialSection";
import { PricingSection } from "@/components/Blocks/PricingSection";
import { FaqSection } from "@/components/Blocks/FaqSection";

export default function Home() {
  return (
    <main className="min-h-screen bg-white dark:bg-black">
      <div className="mx-auto max-w-7xl px-6 pt-40">
        <Hero />
        <LogoCarousel />
        <FeatureSection />
        <TeamSection />
        <TestimonialSection />
        <PricingSection />
        <FaqSection />
      </div>
    </main>
  );
}

No dynamic imports, no lazy-loading config, no context providers wrapping everything. Each section is a completely self-contained component in components/Blocks/. None of them import from each other.

This decision came from watching how developers actually use shadcn templates. The first thing anyone does after cloning is delete the sections they don't need and reorder the ones they keep. With flat imports, removing the Team section is one deleted line. Reordering sections is moving one line. Adding a new section is creating a file and adding one import.

The alternative (a sections array, a renderer loop, a config file that controls order) sounds sophisticated. In practice, it adds indirection that makes the template harder to understand and slower to customize. Templates should be obvious, not impressive.

Lesson: in a template context, the simplest architecture is the correct architecture. The developer cloning your template isn't impressed by abstraction. They want to understand the code fast and change it faster.

Lesson 5: Staggered Animations Without Managing Individual Delays

The Hero section uses entrance animations where each element fades up sequentially: badge first, then heading, then subheading, then CTA. The naïve approach sets a different delay prop on each element manually. The correct approach uses staggerChildren:

// components/Blocks/Hero.tsx
"use client"
import { motion, type Variants } from "motion/react"

const containerVariants: Variants = {
  hidden: { opacity: 0 },
  visible: {
    opacity: 1,
    transition: {
      staggerChildren: 0.15,  // each child animates 150ms after the previous
      delayChildren: 0.1,
    },
  },
}

const fadeUpVariants: Variants = {
  hidden: { opacity: 0, y: 20 },
  visible: {
    opacity: 1,
    y: 0,
    transition: { duration: 0.5, ease: "easeOut" },
  },
}

const Hero = () => (
  <motion.div variants={containerVariants} initial="hidden" animate="visible">
    <motion.div variants={fadeUpVariants}>
      {/* Badge */}
    </motion.div>
    <motion.h1 variants={fadeUpVariants}>
      AI Chatbot for Customer Support.
    </motion.h1>
    <motion.p variants={fadeUpVariants}>
      {/* Subheading */}
    </motion.p>
    <motion.div variants={fadeUpVariants}>
      {/* CTA */}
    </motion.div>
  </motion.div>
)

The parent defines staggerChildren: 0.15. Every child with variants={fadeUpVariants} automatically inherits a 150ms offset from the previous child. Want to add a new element? Give it variants={fadeUpVariants} and the stagger chain extends automatically. No manually updated delay values.

The Features section uses scroll-triggered animations with a different easing:

// components/Blocks/FeatureSection.tsx
<motion.div
  initial={{ opacity: 0, y: 40 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, amount: 0.3 }}
  transition={{
    duration: 0.5,
    delay: index * 0.15,
    ease: [0.22, 1, 0.36, 1],
  }}
>

viewport={{ once: true }} fires the animation once when the element enters the viewport, not on every scroll pass. amount: 0.3 starts the animation when 30% of the element is visible, not when the full element is on screen. The cubic bezier [0.22, 1, 0.36, 1] is a fast-out-slow-in curve that feels physical rather than mechanical.

Quick note on the import: most of the core API is compatible, but motion/react isn't a straight drop-in rename of framer-motion. If you're upgrading an existing project, check the official migration guide before swapping the import. Layout animations, AnimatePresence behaviour, and some hooks changed.

Lesson: define animation variants at the parent level and use staggerChildren to orchestrate the sequence. Never set delay manually on individual elements — that creates a brittle list of numbers you have to update every time you add or remove an element. Let the parent handle timing; let children just declare what they animate to.

Lesson 6: CSS-Only Infinite Scroll — No Library Needed

The testimonials use a dual-row auto-scrolling marquee. The second row scrolls in reverse. There's no third-party marquee package. It's a small component built entirely on CSS animations defined in Tailwind v4's @theme block.

// components/ui/marquee.tsx
export function Marquee({
  reverse = false,
  pauseOnHover = false,
  vertical = false,
  children,
  repeat = 4,
  ...props
}) {
  return (
    <div className="group flex gap-(--gap) overflow-hidden [--duration:40s] [--gap:2rem]">
      {Array(repeat).fill(0).map((_, i) => (
        <div
          key={i}
          className={cn("flex shrink-0 justify-around gap-(--gap)", {
            "animate-marquee flex-row": !vertical,
            "group-hover:paused": pauseOnHover,
            "[animation-direction:reverse]": reverse,
          })}
        >
          {children}
        </div>
      ))}
    </div>
  )
}

The repeat={4} prop renders the children 4 times side by side. As the CSS animation scrolls the container left, the repetitions create a seamless loop. By the time the first set has scrolled off screen, the second set is already in position.

group-hover:paused is Tailwind applying animation-play-state: paused when the parent has group class and is hovered. No onMouseEnter/onMouseLeave handlers or state, just pure CSS.

To customize the scroll speed without touching the component source, you override the CSS variable inline:

<Marquee pauseOnHover className="[--duration:20s]">
  {items.map(item => <Card key={item.id} {...item} />)}
</Marquee>

[--duration:20s] is a Tailwind arbitrary property. It sets --duration directly on the element, which the animation reads via var(--duration). Speed customization without a prop, without touching the component.

Lesson: before reaching for a third-party animation package, check whether a CSS keyframe animation and a couple of Tailwind utilities can do the same job. A marquee, a fade loop, a pulsing skeleton — all of these are achievable with native CSS. Fewer dependencies means fewer breaking changes when the ecosystem moves.

Lesson 7: CSS Subgrid Solves Pricing Card Alignment Natively

The pricing section has three cards: Free, Pro, and Business. Each card has four rows: plan name, price, CTA button, and features list. The features list height varies between plans. Without CSS subgrid, the rows don't align across cards.

The common workaround is min-height on each row, or JavaScript that measures each card and sets explicit heights. Both approaches are fragile. Subgrid solves it in CSS:

// components/Blocks/PricingSection.tsx
<div className="grid lg:grid-cols-3">
  {plans.map((plan) => (
    <div className="p-8 grid grid-rows-subgrid row-span-4 gap-6">
      <div>{/* Plan name + description */}</div>
      <div>{/* Price */}</div>
      <div>{/* CTA button */}</div>
      <div>{/* Features list */}</div>
    </div>
  ))}
</div>

grid-rows-subgrid tells each card to participate in the parent grid's row tracks rather than creating its own. Each card spans 4 rows (row-span-4). The plan name row, price row, CTA row, and features row align across all three cards (regardless of content height) because they're all on the same row tracks.

Each card's row-span-4 reserves four rows in the parent's implicit grid. Because every card spans the same four shared row tracks, their internal rows align automatically even though the parent never declares explicit row heights.

CSS subgrid has been in all modern browsers since late 2023. There's no reason to reach for a JavaScript layout solution when the platform handles it.

Lesson: when you have a grid of cards where each card has multiple internal rows that need to align across columns, reach for grid-rows-subgrid before reaching for min-height or JavaScript. Define the number of rows each card spans with row-span-N, and the browser handles the rest.

Lesson 8: Inline SVGs Beat Image Libraries for Simple Logos

The logo carousel renders 12 brand logos: Shopify, Stripe, GitHub, Google, and others. The first instinct is to use a package like react-icons or simple-icons. I went a different direction: inline SVG paths stored as a plain TypeScript object.

// components/Blocks/LogoCarousel.tsx
const iconMap = {
  stripe: "M13.976 9.15c-2.172-.806...",
  github: "M12 .297c-6.63 0-12...",
  google: "M12.48 10.92v3.28h7.84...",
  // ...
} as const

const SimpleIcon = ({ iconSlug, size = 24 }: { iconSlug: string; size?: number }) => {
  const iconPath = iconMap[iconSlug as keyof typeof iconMap]
  return (
    <svg role="img" viewBox="0 0 24 24" className="fill-black dark:fill-white">
      <path d={iconPath} />
    </svg>
  )
}

The fill-black dark:fill-white class means every logo automatically inverts in dark mode: no separate dark mode logo assets, and no conditional rendering based on theme.

The carousel itself duplicates the logo array to create a seamless loop:

{/* First pass */}
{techCompanies.map((company, i) => <LogoCard key={`first-${i}`} {...company} />)}
{/* Second pass — identical, creates the seamless loop */}
{techCompanies.map((company, i) => <LogoCard key={`second-${i}`} {...company} />)}

The CSS animation (animate-logo-scroll) scrolls the container left. When the first pass disappears off the left edge, the second pass is already in position. The loop is seamless.

The trade-off: maintaining SVG paths manually is fine for a fixed set of logos. If you need a large dynamic icon set, reach for simple-icons or a proper icon library. For 12 brand logos that rarely change, this approach ships zero extra dependencies.

Lesson: match your tooling to your actual requirements. A logo carousel with a fixed set of brand logos doesn't need an icon library — it needs a TypeScript object and two Tailwind classes. Installing a package to solve a problem you could solve with 10 lines of code adds maintenance surface for no gain.

What I'd Do Differently

These are the three decisions I'd change if starting the template today.

1. Extract Animation Variants to a Shared File

containerVariants and fadeUpVariants are currently defined locally in both Hero.tsx and FeatureSection.tsx. If you want to change the global animation timing (say, reduce duration from 0.5s to 0.3s) you update two files. A shared lib/animations.ts exporting the standard variants would make global timing changes a one-line edit.

// lib/animations.ts
export const fadeUpVariants: Variants = {
  hidden: { opacity: 0, y: 20 },
  visible: { opacity: 1, y: 0, transition: { duration: 0.5, ease: "easeOut" } },
}

export const containerVariants: Variants = {
  hidden: { opacity: 0 },
  visible: { opacity: 1, transition: { staggerChildren: 0.15, delayChildren: 0.1 } },
}

2. Use Subgrid in the Features Section Too

The Features grid uses a border-based visual separation pattern — borders between cells create the grid appearance. It works, but the hover states have an inconsistency: the gradient hover overlay height varies slightly between cells in the same row because content heights differ. Subgrid would lock those row heights across cards the same way it does in the Pricing section.

3. Use next/font More Consistently

The layout loads both Geist and Inter font families. Inter is used via --font-sans. Geist is loaded but the geistSans.variable and geistMono.variable are applied to <body> as className strings while Inter drives the actual font rendering through the CSS variable. The result is that Geist is loaded but not actually displayed. Cleaning this up could shave tens of kilobytes from the font payload — worth verifying in Lighthouse or the Network tab before deploying.

Summary

These are the five things from this build worth taking into your next project:

1. shadcn/ui's base-nova style runs on Base UI primitives. ARIA state drives visual state — no parallel JavaScript state needed.

2. Tailwind v4 moves theme config to CSS. All theme tokens, custom animations, and radius scales live in CSS via @theme inline. This is the right place for them.

3. OKLCH gives predictable dark mode contrast. Adjusting lightness in OKLCH actually changes perceived brightness. Hex and HSL don't guarantee this.

4. staggerChildren in motion/react eliminates manually managed animation delays. The parent orchestrates while the children just declare their animation variant.

5. CSS subgrid (grid-rows-subgrid) aligns card rows across columns natively. No JavaScript measurement, no fixed heights.

The full template is MIT-licensed and available at github.com/ShadcnDeck/chatdeck-shadcn-saas-landing-page-template. If it's useful, a star helps others find it.

A hero section, feature grid, testimonials, pricing, FAQ, and footer are common building blocks, yet developers often spend hours recreating them for every new project.

In this guide, you'll learn how to build a modern marketing landing page using Next.js, shadcn/ui, Tailwind CSS, and reusable Shadcn blocks. Instead of building every section from scratch, you'll assemble a production-ready page, customize it to match your brand, and finish with a foundation that's ready for real-world projects.

Table of Contents

• Prerequisites

• What Are We Building?

• Project Setup with Base UI Using the Shadcn Preset

• Two Ways to Build Your Marketing Landing Page

• Option 1: Build Using the CLI

• Option 2: Build Using the MCP Server

• How to Optimize Your Landing Page

• How to Expand Your Marketing Website

• Live Preview:

• Conclusion

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 Are We Building?

In this tutorial, we'll build a modern marketing landing page using production-ready blocks from Shadcn Space. Instead of designing and developing every section from scratch, we'll assemble a complete landing page using reusable shadcn/ui blocks and customize them to fit our brand and product.

You can use the same approach to create landing pages for SaaS products, AI tools, startups, agencies, developer tools, portfolios, and many other types of websites. Since every block is built with React, Tailwind CSS, and shadcn/ui, you have full control over the code and can easily modify the content, layout, and styling.

Why Build with Shadcn Space?

Creating a professional marketing website typically involves designing multiple sections that work together to tell your product's story and guide visitors to take action.

But instead of building every section from scratch, you can start with production-ready blocks that are easy to customize.

This lets you build marketing websites faster with reusable blocks (and you can also mix and match blocks to create unique page layouts). It also gives you full ownership of your clean React and Tailwind CSS code. And overall, you save development time without sacrificing flexibility.

Sections We'll Build

We'll build our marketing landing page using the following sections:

• Hero section with a compelling headline, call-to-action, and trusted-by logos.

• Features section to highlight your product's key capabilities.

• Product Showcase & Benefits section to demonstrate your product and communicate its value.

• Testimonials section to build credibility with customer feedback.

• Pricing section to present your plans clearly.

• FAQ section answers common questions and reduces friction.

• Call-to-Action section to encourage visitors to get started.

• Footer with navigation and important links.

Final Page Structure

Our landing page will have this structure:

<main>
  {/* 1. Hero section + Trusted by / Logo cloud */}
  <AgencyHeroSection />

  {/* 2. Features section */}
  <Feature01 />

  {/* 3. Product showcase & Benefits */}
  <AboutAndStats01 />

  {/* 4. Testimonials */}
  <Testimonials />

  {/* 5. Pricing section */}
  <Pricing />

  {/* 6. FAQ section */}
  <Faq />

  {/* 7. Call-to-action section */}
  <CTA />

  {/* Footer */}
  <Footer />
</main>

Each section will be installed from the Shadcn Space registry and customized directly inside our project. By the end of this tutorial, you'll have a fully responsive marketing landing page built with Next.js, Tailwind CSS, and shadcn/ui that you can adapt for your own product or business.

Project Setup with Base UI Using the Shadcn Preset

Since Shadcn Space blocks are built using Base UI primitives, we'll create our project using the Base UI preset instead of the default Radix setup.

This ensures that our landing page uses the same foundation as the blocks we're going to install.

1. Create the Project with Base UI

Run the following command:

pnpm dlx shadcn@latest init --preset b0 --template next

This command does a few important things:

• Creates a Next.js project

• Configures Tailwind CSS

• Sets up Base UI as the component foundation

• Uses the Nova style preset

• Configures Lucide icons

• Uses Inter font

• Applies neutral theme tokens

You now have a Base UI-powered Next.js project ready for building your landing page.

2. Add the Shadcn Space Registry

Open your components.json and add the following registry configuration:

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

This tells the CLI where to fetch components and blocks from the registry.

For more information about how to use it in your project, check out the docs.

Two Ways to Build Your Marketing Landing Page

Now that your project is set up with shadcn/ui, it's time to start building the marketing landing page.

You can install production-ready blocks directly into your project in two different ways:

• Using the CLI

• Using the MCP Server inside your AI-powered editor

Both approaches install the actual React and Tailwind CSS source code into your project, giving you complete control over customization. The only difference is how you discover and install the blocks.

Option 1: Build Using the CLI

The CLI is the fastest way to browse the registry and install individual blocks into your project. It gives you full control over which sections you want to use and how you customize them.

Step 1: Browse Marketing Blocks

Visit the block registry and explore the available marketing blocks.

Let's review the sections we'll use for this tutorial:

• Hero section with a call-to-action and trusted-by logos

• Features section

• Product showcase & benefits section

• Testimonials section

• Pricing section

• FAQ section

• Call-to-action section

• Footer

Choose the blocks that best match the design and style of your website. Since every block is fully customizable, you can easily update the content, colors, spacing, and layout to match your brand.

In the following sections, we'll install each block and customize them.

Step 2: Install Selected Blocks

Once you find a block you like, install it using the CLI:

npx shadcn@latest add @shadcn-space/{block-name}

Each command downloads the block, places it inside components/shadcn-space/blocks, and installs the required dependencies.

Now your folder might look like this:

components/
  shadcn-space/
    blocks/
      about-us-section-01/
      hero-01/
      features-01/
      pricing-01/
      testimonial-01/
      faq-01/
      cta-01/
      footer-01/

Note: I've used the first block from each section in this tutorial. You can choose any other shadcn block that suits best according to your needs.

Step 3: Add a Hero Section

Every great marketing landing page starts with a strong hero section. It's the first thing visitors see, so it should clearly communicate what your product does, who it's for, and encourage users to take action.

Instead of building the section from scratch, we'll install a production-ready Hero block and customize it to match our landing page.

1. Install the Hero Block

Run the following CLI command to add the Hero block to your project:

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

The CLI will automatically download the Hero block source code, add the component to your project, and install any required dependencies.

After the installation completes, you should see the following directory structure:

components/
  shadcn-space/
    blocks/
      hero-01/
        index.tsx

You can now open the component and customize the heading, description, call-to-action buttons, images, and other content to match your product and branding.

2. Understand the Hero Block Structure

Once the installation is complete, open the Hero block located at:

components/shadcn-space/blocks/hero-01/index.tsx

You'll see a component similar to the following:

import HeroSection from "@/components/shadcn-space/blocks/hero-01/hero";
import type { NavigationSection } from "@/components/shadcn-space/blocks/hero-01/header";
import Header from "@/components/shadcn-space/blocks/hero-01/header";
import BrandSlider, { BrandList } from "@/components/shadcn-space/blocks/hero-01/brand-slider";
import type { AvatarList } from "@/components/shadcn-space/blocks/hero-01/hero";

export default function AgencyHeroSection() {
  const avatarList: AvatarList[] = [...];
  const navigationData: NavigationSection[] = [...];
  const brandList: BrandList[] = [...];

  return (
    <div className="relative">
      <Header navigationData={navigationData} />
      <main>
        <HeroSection avatarList={avatarList} />
        <BrandSlider brandList={brandList} />
      </main>
    </div>
  );
}

What Should You Notice?

Before making any changes, take a moment to understand how the block is organized. Rather than being a single large component, it's composed of smaller, reusable components that work together.

In this example:

• The Header component renders the navigation and receives its menu items through the navigationData array.

• The HeroSection component contains the main headline, description, call-to-action buttons, and social proof, while the avatarList provides the data displayed in the hero.

• The BrandSlider component displays the company logos using the brandList array.

This separation keeps the code modular and makes each part of the landing page easier to customize or replace independently.

Why This Matters?

Because the block is copied directly into your project, you're working with standard React components instead of a compiled package. Every file is fully editable, allowing you to understand how the section is built and modify it to suit your own requirements.

For example, you can update the navigation links, replace the placeholder content with your own branding, add additional sections, integrate custom functionality, or adjust the styling using Tailwind CSS classes. Since everything lives inside your codebase, you're free to restructure the component however you like without being locked into predefined APIs or abstractions.

3. Render the Hero Section

Now that the Hero block has been installed, it's time to display it on the page.

Import the component into your app/page.tsx file:

import AgencyHeroSection from "@/components/shadcn-space/blocks/hero-01";

export default function Page() {
  return (
    <AgencyHeroSection />
  );
}

Save the file and start your development server if it isn't already running. When you open the application in your browser, you'll see the Hero section rendered as the first part of your marketing landing page.

With the Hero section in place, we've completed the first building block of our landing page. Next, we'll continue by adding the remaining sections to create a complete marketing website.

Install the Remaining Blocks

Now that you've added and rendered the Hero section, let's install the remaining blocks required for our marketing landing page.

Run the following command to install all the remaining sections at once:

npx shadcn@latest add @shadcn-space/feature-01 @shadcn-space/about-us-section-01 @shadcn-space/testimonial-01 @shadcn-space/pricing-01 @shadcn-space/faq-01 @shadcn-space/cta-01  @shadcn-space/footer-01

Note: If you're using Windows Command Prompt or PowerShell, run the command on a single line instead of using \ for line continuation.

After the installation is complete, update your app/page.tsx by importing the newly added blocks and rendering them in the following order:

import AgencyHeroSection from "@/components/shadcn-space/blocks/hero-01";
import AboutAndStats01 from "@/components/shadcn-space/blocks/about-us-01";
import Feature01 from "@/components/shadcn-space/blocks/feature-01";
import Pricing from "@/components/shadcn-space/blocks/pricing-01/pricing";
import Testimonials from "@/components/shadcn-space/blocks/testimonial-01/testimonial";
import Faq from "@/components/shadcn-space/blocks/faq-01/faq";
import CTA from "@/components/shadcn-space/blocks/cta-01/cta";
import Footer from "@/components/shadcn-space/blocks/footer-01/footer";


export const metadata = {
  title: "Acme Agency – Innovative Digital Solutions",
  description:
    "We craft immersive digital experiences for bold brands. Explore our services, pricing, and success stories.",
};


export default function Page() {
  return (
    <main>
      {/* 1. Hero section + Trusted by / logo cloud */}
      <AgencyHeroSection />


      {/* 2. Features section */}
      <Feature01 />


      {/* 3. Product showcase & Benefits section (Using About/Stats as a placeholder for these) */}
      <AboutAndStats01 />


      {/* 4. Testimonials */}
      <Testimonials />


      {/* 5. Pricing section */}
      <Pricing />


      {/* 6. FAQ section */}
      <Faq />


      {/* 7. Call-to-action section */}
      <CTA />


      {/* Footer */}
      <Footer />
    </main>
  );
}

That's it! Your complete marketing landing page is now assembled. You can start customizing the content, images, colors, and layout of each section to match your product and brand.

Customize the Marketing Landing Page

At this point, the overall structure of your marketing landing page is complete. The next step is to personalize each section so it reflects your product, brand, and messaging instead of the default placeholder content.

One of the biggest advantages of working with reusable React components is that every section can be customized independently. You can update the content, replace images, adjust layouts, and refine the styling without rebuilding the page from scratch.

The following examples show how the default blocks can be transformed into a polished marketing website.

Customize the Hero Section

The Hero section is the first thing visitors see, so it's the most important place to communicate your product's value. Replace the placeholder headline, supporting text, call-to-action buttons, and trusted brand logos with content that represents your own business.

Before:

After:

Notice how the customized version immediately establishes the product's identity through updated messaging, branding, imagery, and call-to-action buttons.

Customize the Features Section

The Features section should explain what your product offers and why it stands out. Replace the sample feature cards with capabilities that highlight your product's most valuable functionality.

Before:

After:

Updating the feature titles, descriptions, and icons makes the section more relevant to your audience while reinforcing your product's key selling points.

Customize the Pricing Section

Your pricing section should clearly communicate the plans you offer and help visitors choose the option that best fits their needs. Replace the default plans, pricing, feature lists, and button labels with information that matches your business model.

Before:

After:

A customized pricing section builds trust by presenting accurate information while making it easier for potential customers to compare plans.

Customize the FAQ Section

The FAQ section is a great opportunity to answer common questions before visitors contact your team. Replace the placeholder questions with answers related to your product, pricing, integrations, support, or onboarding process.

Before:

After:

Tailoring the FAQ to your product helps reduce uncertainty, improves the user experience, and can answer many questions before a customer reaches out.

The Result

With just a few content updates, the default blocks evolve into a professional marketing landing page tailored to your brand. Since every section is built with reusable React components, you can continue refining the design, adjusting layouts, and adding new content as your product grows without changing the overall page structure.

Option 2: Build Using the MCP Server

If you prefer a faster workflow, you can use the MCP Server to generate your landing page directly inside your editor. Instead of manually browsing and installing individual blocks, you simply describe the page you want to build, and the MCP Server assembles an initial version for you.

The MCP Server works with supported editors like Antigravity, VS Code, Cursor, Windsurf, and other MCP-compatible editors.

Step 1: Install the MCP Server

Quick Installation:

The fastest way to get started. Choose your package manager and run the command corresponding to your client:

For Claude Code:

claude mcp add shadcnspace-mcp -- npx -y shadcnspace-mcp@latest

For Others:

npx shadcnspace-cli install <client>

Replace <client> with cursor, antigravity, vscode, or windsurf.

Manual Installation For VS Code:

{
  "servers": {
    "shadcnspace-mcp": {
      "command": "npx",
      "args": ["-y", "shadcnspace-mcp@latest"]
    }
  }
}

• Open .vscode/mcp.json.

• Click Start next to the Shadcn Space MCP server

For a detailed guide, follow the MCP Server documentation to install it for your preferred editor.

Once the installation is complete, restart your editor to enable the MCP connection.

Step 2: Open the AI Chat

Open the AI chat panel inside your editor and describe the landing page you'd like to create.

For example:

Create a modern marketing landing page for an AI SaaS product.

Use Shadcn Space blocks and include:

- Hero section
- Features section
- Product showcase & benefits
- Testimonials
- Pricing
- FAQ
- Call-to-action
- Footer

Use a clean, modern, and responsive design.

Feel free to replace the product description with your own and customize as you like.

Step 3: Generate the Landing Page

After receiving your prompt, the MCP Server analyzes your requirements and selects the most suitable blocks for your landing page. It automatically assembles the page using a combination of reusable sections, giving you a working layout in just a few moments.

The generated sections are added directly to your project as standard React components. Since everything is real source code, you can customize every part of the page: update the content, replace images, modify the layout, adjust spacing, or restyle components using Tailwind CSS.

The MCP Server simply speeds up the initial setup, while giving you complete control over the final implementation.

How to Optimize Your Landing Page

Building a visually appealing landing page is only the first step. Before publishing your website, it's worth spending some time optimizing it for performance, search engines, and user experience.

A fast, responsive landing page not only feels more polished but also helps improve engagement and conversion rates. Fortunately, Next.js provides several built-in features that make these optimizations straightforward.

Optimize Images with Next.js

Images are often the largest assets on a marketing website, so optimizing them can significantly improve loading performance. If you're using Next.js, prefer the built-in next/image component instead of the standard HTML image tag. It automatically serves appropriately sized images, supports modern image formats, and reduces layout shifts as the page loads.

Before adding screenshots or illustrations to your project, make sure they're compressed and sized appropriately. Well-optimized images create a smoother browsing experience across desktop and mobile devices while also contributing to better Core Web Vitals.

Improve SEO for Your Landing Page

A well-designed landing page is only effective if people can discover it. Search engine optimization starts with creating meaningful content that clearly communicates what your product offers. Choose a descriptive page title, write a concise meta description, and organize your content using logical headings.

Your primary keyword should appear naturally throughout the page without forcing it into every paragraph. Focus on writing for your audience first, then structure the content in a way that search engines can easily understand. Combining valuable content with a clear page hierarchy gives your landing page the best chance of ranking for relevant searches.

Add Metadata and Open Graph Images

When someone shares your landing page on social media or in a messaging application, the preview is generated from your page's metadata. Configuring Open Graph and Twitter metadata allows you to control the title, description, and preview image that appear when your website is shared.

A custom preview image that reflects your branding makes your links look more professional and can encourage more people to click through. Taking a few minutes to configure these settings helps create a more polished experience whenever your content is shared online.

Optimize Performance

Performance plays a major role in how visitors perceive your website. A page that loads quickly feels more responsive and encourages users to continue exploring your content. As you customize your landing page, keep unnecessary JavaScript to a minimum, optimize static assets, and avoid loading resources that aren't immediately needed.

Even small improvements, such as reducing image sizes or simplifying animations, can noticeably improve loading speed. Before deploying your project, test the page under different network conditions to ensure it performs well for all visitors.

Improve Core Web Vitals

Core Web Vitals are Google's metrics for measuring real-world user experience. They evaluate how quickly your main content appears, how responsive the page feels during interactions, and whether elements remain stable as the page loads. Monitoring these metrics throughout development helps identify potential issues before they affect users.

Tools such as Lighthouse and PageSpeed Insights provide detailed reports that can help you improve loading performance and responsiveness. A landing page with strong Core Web Vitals not only creates a better experience for visitors but can also contribute to improved search rankings.

How to Expand Your Marketing Website

A landing page is often just the beginning of a complete marketing website. As your product grows, you'll likely need additional pages that provide more information, improve navigation, and create a better experience for your visitors. Common additions include Blog, Blog Details, Pricing, FAQ, Changelog, Contact, Integration, Error, and About Us pages.

Building these pages with a consistent design system helps maintain a unified look and feel across your entire website while reducing development time. Reusing layouts and components also makes your project easier to maintain as it evolves.

If you're looking to expand your website beyond a single landing page, explore the collection of production-ready Shadcn website pages, built with React, Next.js, Tailwind CSS, and shadcn/ui.

Live Preview:

Conclusion

In this tutorial, we built a complete marketing landing page using Next.js, shadcn/ui, Tailwind CSS, and reusable Shadcn Space blocks. Starting from a fresh project, we assembled a production-ready page by combining sections such as the Hero, Features, Product Showcase, Testimonials, Pricing, FAQ, Call-to-Action, and Footer.

Because every block is added as standard React source code, you're free to customize the content, layout, styling, and functionality to match your own product and branding. Whether you're building a SaaS application, a startup website, an AI product, an agency site, or a developer tool, the same approach can be adapted to your requirements.

A marketing landing page is just the foundation of your online presence. As your product grows, you can continue expanding your website with additional marketing pages while maintaining a consistent design system and development workflow.

I hope this guide has helped you understand how to quickly build a modern, responsive marketing landing page using reusable components. Feel free to experiment with different block combinations, personalize the design, and create a website that best represents your product.

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

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

1. A Shopping Cart Sheet with quantity controls, item removal, and a live subtotal.

2. 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.

Table of Contents

• 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 (
    <Sheet>
      <SheetTrigger render={<Button variant="outline" size="icon" className="relative cursor-pointer" />}>
        <ShoppingCartIcon size={18} />
        {totalCount > 0 && (
          <Badge className="absolute -top-2 -right-2 size-5 justify-center rounded-full p-0 text-[10px]">
            {totalCount}
          </Badge>
        )}
      </SheetTrigger>

      <SheetContent side="right" className="flex flex-col p-0 gap-0">
        <SheetHeader className="px-4 pt-5 pb-4 border-b">
          <SheetTitle>Your Cart</SheetTitle>
          <SheetDescription>
            {totalCount > 0
              ? `${totalCount} item${totalCount > 1 ? "s" : ""} in your cart`
              : "Your cart is empty"}
          </SheetDescription>
        </SheetHeader>

        <div className="flex-1 overflow-y-auto px-4 py-3 flex flex-col gap-3">
          {items.map((item) => (
            <div key={item.id} className="flex items-start gap-3">
              <div className="size-16 rounded-lg bg-muted shrink-0 overflow-hidden">
                <img src={item.image} alt={item.name} className="size-full object-cover" />
              </div>
              <div className="flex-1 min-w-0">
                <p className="text-sm font-medium leading-snug truncate">{item.name}</p>
                <p className="text-xs text-muted-foreground">{item.variant}</p>
                <p className="text-sm font-semibold mt-1">${item.price.toFixed(2)}</p>
              </div>
              <div className="flex flex-col items-end gap-2 shrink-0">
                <Button
                  variant="ghost"
                  size="icon-sm"
                  className="text-muted-foreground hover:text-destructive hover:bg-destructive/10! cursor-pointer"
                  onClick={() => updateQty(item.id, -item.qty)}
                >
                  <Trash2Icon size={14} />
                </Button>
                <ButtonGroup>
                  <Button variant="outline" size="icon-sm" className="cursor-pointer" onClick={() => updateQty(item.id, -1)}>
                    <MinusIcon />
                  </Button>
                  <ButtonGroupText className="px-2 text-sm min-w-7 justify-center">{item.qty}</ButtonGroupText>
                  <Button variant="outline" size="icon-sm" className="cursor-pointer" onClick={() => updateQty(item.id, 1)}>
                    <PlusIcon />
                  </Button>
                </ButtonGroup>
              </div>
            </div>
          ))}
        </div>

        <SheetFooter className="flex flex-col gap-3 px-4 pt-3 pb-5 border-t">
          <div className="flex flex-col gap-1.5 w-full">
            <div className="flex justify-between text-sm text-muted-foreground">
              <span>Subtotal</span>
              <span>${subtotal.toFixed(2)}</span>
            </div>
            <div className="flex justify-between text-sm text-muted-foreground">
              <span>Shipping</span>
              <span className="text-teal-400">Free</span>
            </div>
            <Separator className="my-1" />
            <div className="flex justify-between text-sm font-semibold">
              <span>Total</span>
              <span>${subtotal.toFixed(2)}</span>
            </div>
          </div>
          <Button className="w-full cursor-pointer hover:bg-primary/80">Checkout</Button>
          <SheetClose render={<Button variant="outline" className="w-full cursor-pointer" />}>
            Continue Shopping
          </SheetClose>
        </SheetFooter>
      </SheetContent>
    </Sheet>
  );
};

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={<Button ... />}) rather than wrapping children in an asChild pattern. This is the Base UI convention that Shadcn Space components use, and it keeps the button's accessibility behavior (focus states, keyboard handling) entire instead of overriding it with a custom wrapper.

4. Fixed header and footer, scrollable middle

<SheetContent className="flex flex-col p-0 gap-0">
  <SheetHeader className="border-b" />
  <div className="flex-1 overflow-y-auto">{/* items */}</div>
  <SheetFooter className="border-t" />
</SheetContent>

flex-1 overflow-y-auto on the middle div is what keeps the header and footer fixed while the item list scrolls independently. Skip this, and a long cart pushes the checkout button off-screen.

Live Preview:

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

What the Filter Sheet Does

The Filters button slides a panel in from the left with category checkboxes, a price range slider, a star rating filter, and an availability toggle. An active filter count shows on the trigger button itself, and clearing filters resets the state without closing the panel.

How to Install the Filter Sheet

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

The CLI copies the component into:

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

The Component Code

"use client";

import { useState } from "react";
import { SlidersHorizontalIcon, StarIcon } from "lucide-react";
import {
  Sheet,
  SheetTrigger,
  SheetContent,
  SheetHeader,
  SheetTitle,
  SheetDescription,
  SheetFooter,
  SheetClose,
} from "@/components/ui/sheet";
import { Button } from "@/components/ui/button";
import { Checkbox } from "@/components/ui/checkbox";
import { Slider } from "@/components/ui/slider";
import { Label } from "@/components/ui/label";
import { Badge } from "@/components/ui/badge";
import { Separator } from "@/components/ui/separator";

const CATEGORIES = ["Watches", "Clothing", "Beauty", "Electronics", "Home & Living"];
const RATINGS = [4, 3, 2, 1];
const AVAILABILITY = ["In Stock", "On Sale"];

const AdvancedFiltersDemo = () => {
  const [selectedCategories, setSelectedCategories] = useState([]);
  const [priceRange, setPriceRange] = useState([0, 1000]);
  const [selectedRating, setSelectedRating] = useState(null);
  const [selectedAvailability, setSelectedAvailability] = useState([]);

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

  const toggleAvailability = (val) =>
    setSelectedAvailability((prev) => (prev.includes(val) ? prev.filter((v) => v !== val) : [...prev, val]));

  const clearAll = () => {
    setSelectedCategories([]);
    setPriceRange([0, 1000]);
    setSelectedRating(null);
    setSelectedAvailability([]);
  };

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

  return (
    <Sheet>
      <SheetTrigger render={<Button variant="outline" className="relative cursor-pointer gap-2" />}>
        <SlidersHorizontalIcon size={16} />
        Filters
        {activeCount > 0 && (
          <Badge className="size-5 justify-center rounded-full p-0 text-[10px]">{activeCount}</Badge>
        )}
      </SheetTrigger>

      <SheetContent side="left" className="flex flex-col p-0 gap-0">
        <SheetHeader className="px-4 pt-5 pb-4 border-b">
          <SheetTitle>Filters</SheetTitle>
          <SheetDescription>Narrow down products by your preferences.</SheetDescription>
        </SheetHeader>

        <div className="flex-1 overflow-y-auto px-4 py-4 flex flex-col gap-5">
          <div className="flex flex-col gap-3">
            <p className="text-sm font-medium">Category</p>
            {CATEGORIES.map((cat) => (
              <div key={cat} className="flex items-center gap-2.5">
                <Checkbox id={`cat-${cat}`} checked={selectedCategories.includes(cat)} onCheckedChange={() => toggleCategory(cat)} />
                <Label htmlFor={`cat-${cat}`} className="text-sm font-normal cursor-pointer">{cat}</Label>
              </div>
            ))}
          </div>

          <Separator />

          <div className="flex flex-col gap-4">
            <div className="flex items-center justify-between">
              <p className="text-sm font-medium">Price Range</p>
              <span className="text-xs text-muted-foreground">${priceRange[0]} -- ${priceRange[1]}</span>
            </div>
            <Slider value={priceRange} onValueChange={(val) => setPriceRange(Array.isArray(val) ? [...val] : [val])} min={0} max={1000} step={10} />
          </div>

          <Separator />

          <div className="flex flex-col gap-3">
            <p className="text-sm font-medium">Rating</p>
            {RATINGS.map((rating) => (
              <div key={rating} className="flex items-center gap-2.5 cursor-pointer" onClick={() => setSelectedRating(selectedRating === rating ? null : rating)}>
                <Checkbox id={`rating-${rating}`} checked={selectedRating === rating} onCheckedChange={() => setSelectedRating(selectedRating === rating ? null : rating)} />
                <Label htmlFor={`rating-${rating}`} className="flex items-center gap-1 text-sm font-normal cursor-pointer">
                  {Array.from({ length: rating }).map((_, i) => <StarIcon key={i} size={13} className="fill-amber-400 text-amber-400" />)}
                  {Array.from({ length: 5 - rating }).map((_, i) => <StarIcon key={i} size={13} className="text-muted-foreground/40" />)}
                  <span className="ml-0.5 text-muted-foreground">& up</span>
                </Label>
              </div>
            ))}
          </div>

          <Separator />

          <div className="flex flex-col gap-3">
            <p className="text-sm font-medium">Availability</p>
            {AVAILABILITY.map((val) => (
              <div key={val} className="flex items-center gap-2.5">
                <Checkbox id={`avail-${val}`} checked={selectedAvailability.includes(val)} onCheckedChange={() => toggleAvailability(val)} />
                <Label htmlFor={`avail-${val}`} className="text-sm font-normal cursor-pointer">{val}</Label>
              </div>
            ))}
          </div>
        </div>

        <SheetFooter className="flex flex-row gap-2 px-4 pt-3 pb-5 border-t">
          <Button variant="outline" className="flex-1 cursor-pointer" onClick={clearAll}>Clear All</Button>
          <SheetClose render={<Button className="flex-1 cursor-pointer hover:bg-primary/80" />}>Apply Filters</SheetClose>
        </SheetFooter>
      </SheetContent>
    </Sheet>
  );
};

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

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

npx shadcn@latest add @shadcn-space/<identifier>

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

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 <div>. 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:

1. A Preview Card with a group hover image effect, an overlay arrow icon, and a property details layout

2. An Analytics Card with typed metric props, conditional badge colors, and a decorative background image

3. A Statistics Card with a responsive four-column e-commerce stats grid and icon badges

4. An Ecommerce Product Variant Card with size selection, a wishlist toggle, a bag button, and a ripple animation on the buy button

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)

• 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 = () => (
  <Card className="relative gap-0 py-0 rounded-2xl group hover:shadow-3xl duration-300">
    <div className="overflow-hidden rounded-t-2xl">
      <a href="#">
        <div className="w-full h-72">
          <img
            src="https://images.shadcnspace.com/assets/card/property-cover-1.jpg"
            alt="Serenity Residential Home"
            width={440}
            height={300}
            className="w-full h-full object-cover rounded-t-2xl group-hover:brightness-50 group-hover:scale-125 transition duration-300 delay-75"
          />
        </div>
      </a>

      <div className="absolute top-6 right-6 hidden p-4 bg-white rounded-full group-hover:block">
        <ArrowRight className="text-card-foreground" />
      </div>
    </div>

    <div className="p-6">
      <div className="flex justify-between gap-5 mb-6">
        <div>
          <a href="#">
            <h3 className="text-xl font-medium duration-300 group-hover:text-primary">
              Serenity Residential Home
            </h3>
          </a>
          <p className="text-base font-normal text-muted-foreground">
            15 S Aurora Ave, Miami
          </p>
        </div>

        <Badge className="px-5 py-4 text-base font-normal rounded-full bg-teal-500/10 text-teal-500">
          $570,000
        </Badge>
      </div>

      <div className="flex">
        <div className="flex flex-col gap-2 xs:pr-4 pr-8 border-e border-border">
          <BedDouble size={20} />
          <p className="text-sm sm:text-base">5 Bedrooms</p>
        </div>

        <div className="flex flex-col gap-2 xs:px-4 px-8 border-e border-border">
          <Bath size={20} />
          <p className="text-sm sm:text-base">3 Bathrooms</p>
        </div>

        <div className="flex flex-col gap-2 xs:pl-4 pl-8">
          <Expand size={20} />
          <p className="text-sm sm:text-base">
            120m<sup>2</sup>
          </p>
        </div>
      </div>
    </div>
  </Card>
);

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 (
    <div className="flex items-center justify-center w-full">
      <div className="max-w-7xl mx-auto px-4 lg:px-8 xl:px-16 py-10 w-full">
        <Card className="p-0 ring-0 border rounded-2xl relative h-full max-w-xl w-full mx-auto">
          <CardContent className="p-0">
            <div className="ps-6 py-4 flex flex-col gap-9 justify-between">
              <div>
                <p className="text-lg font-medium text-card-foreground">
                  {mainDashboard.title}
                </p>
                <p className="text-xs font-normal text-muted-foreground">
                  {mainDashboard.description}
                </p>
              </div>
              <div className="flex items-center gap-6">
                {mainDashboard.metrics.map((metric, index) => (
                  <div key={index} className="flex items-center gap-6">
                    <div>
                      <p className="text-xs font-normal text-muted-foreground">
                        {metric.label}
                      </p>
                      <div className="flex items-center gap-1">
                        <p className="text-2xl font-medium text-card-foreground">
                          {metric.value}
                        </p>
                        <Badge
                          className={cn(
                            "font-normal text-muted-foreground",
                            metric.isPositive
                              ? "bg-teal-400/10"
                              : "bg-red-500/10"
                          )}
                        >
                          {metric.percentage}
                        </Badge>
                      </div>
                    </div>
                    {index < mainDashboard.metrics.length - 1 && (
                      <Separator orientation="vertical" className="h-12" />
                    )}
                  </div>
                ))}
              </div>
            </div>

            <img
              src="https://images.shadcnspace.com/assets/backgrounds/stats-01.webp"
              alt="stats chart"
              width={211}
              height={168}
              className="absolute bottom-0 right-0 hidden sm:block"
            />
          </CardContent>
        </Card>
      </div>
    </div>
  );
};

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 && (
  <Separator orientation="vertical" className="h-12" />
)}

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 (
    <div className="max-w-7xl mx-auto px-4 w-full">
      <Card className="p-0">
        <CardContent className="flex items-center w-full lg:flex-nowrap flex-wrap px-0">
          {EcommerceActions.map((item, index) => (
            <div
              className="lg:w-3/12 md:w-6/12 w-full border-e border-border last:border-e-0"
              key={index}
            >
              <div className="p-6">
                <div className="flex flex-col gap-1">
                  <div className="flex justify-between items-start">
                    <h5 className="text-base font-medium">{item.title}</h5>
                    <div className="p-3 rounded-full outline outline-border text-primary">
                      <Icon icon={item.cardIcon} width={16} height={16} />
                    </div>
                  </div>
                  <div className="flex flex-col gap-1">
                    <h5 className="text-2xl font-semibold">{item.subtitle}</h5>
                    <div className="flex items-center gap-2">
                      <p className="text-xs text-muted-foreground">Last 7 days</p>
                      <Badge className={`${item.badgeColor} text-muted-foreground`}>
                        <div className="flex items-center gap-1">
                          {item.statusValue}
                          <Icon icon={item.statusIcon} width={14} height={14} />
                        </div>
                      </Badge>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          ))}
        </CardContent>
      </Card>
    </div>
  );
};

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 (
    <div className="flex items-center justify-center p-8 w-full bg-background">
      <Card className="w-80 rounded-2xl overflow-hidden p-0 gap-0 group/card">

        {/* Image zone */}
        <div className="relative overflow-hidden h-80">
          <img
            src="https://images.shadcnspace.com/assets/card/running-shoe-3d.png"
            className="object-contain drop-shadow-2xl px-8 py-6 transition-transform duration-500 ease-out group-hover/card:scale-105"
            alt="Nike Air Max Pulse"
          />

          {/* Discount badge */}
          <span className="absolute top-3 left-3 text-xs tracking-widest font-bold uppercase bg-foreground text-background px-2.5 py-1 rounded-sm select-none">
            -21%
          </span>

          {/* Wishlist button */}
          <button
            onClick={() => setIsWishlisted(!isWishlisted)}
            title="Wishlist"
            className={cn(
              "absolute top-3 right-3 h-8 w-8 rounded-full border shadow-sm flex items-center justify-center transition-all duration-200 hover:scale-110 active:scale-95",
              isWishlisted
                ? "bg-rose-50 border-rose-200 dark:bg-rose-950 dark:border-rose-800"
                : "bg-background"
            )}
          >
            <Heart
              className={cn(
                "w-3.5 h-3.5 transition-colors",
                isWishlisted ? "fill-rose-500 text-rose-500" : "text-muted-foreground"
              )}
            />
          </button>
        </div>

        {/* Info zone */}
        <CardContent className="px-4 pt-4 pb-4 space-y-1.5">
          <div className="min-w-0">
            <h3 className="text-base font-bold text-foreground truncate">Nike</h3>
            <p className="text-sm text-muted-foreground truncate">
              Air Max Pulse Running Shoes
            </p>
          </div>

          <div className="flex items-center gap-2 pt-1">
            <span className="text-green-600 dark:text-green-500 font-semibold text-sm">
              Down 21%
            </span>
            <span className="text-muted-foreground line-through text-sm">$150</span>
            <span className="text-foreground font-bold text-base">$119</span>
          </div>

          <div className="text-xs text-muted-foreground font-medium">
            Delivery by{" "}
            <span suppressHydrationWarning className="text-foreground font-bold">
              {getDeliveryDate()}
            </span>
          </div>

          {/* Size selector */}
          <div className="flex gap-1.5 pt-2">
            {sizes.map((s, i) => (
              <button
                key={s}
                onClick={() => setActiveSize(i)}
                className={cn(
                  "flex-1 h-7 rounded-lg text-sm font-medium border transition-all duration-150",
                  activeSize === i
                    ? "bg-foreground text-background border-foreground"
                    : "text-muted-foreground hover:border-foreground/50 hover:text-foreground"
                )}
              >
                US {s}
              </button>
            ))}
          </div>
        </CardContent>

        {/* Action zone */}
        <CardFooter className="px-4 pb-6 gap-2 bg-transparent border-t-0">
          <button
            onClick={() => setInBag(!inBag)}
            title={inBag ? "Remove from bag" : "Add to bag"}
            className={cn(
              "h-12 w-12 shrink-0 rounded-xl border flex items-center justify-center transition-all duration-200 hover:scale-105 active:scale-95",
              inBag
                ? "bg-foreground text-background border-foreground"
                : "bg-background text-muted-foreground hover:border-foreground/50 hover:text-foreground"
            )}
          >
            <ShoppingBag className="w-5 h-5" />
          </button>

          <Button className="relative overflow-hidden group/btn flex-1 h-12 rounded-xl font-semibold text-base cursor-pointer border border-primary transition-all flex items-center justify-center gap-2">
            <span className="absolute left-1/2 -translate-x-1/2 top-full -translate-y-1/2 w-8 h-8 bg-white dark:bg-gray-950 rounded-full scale-0 transition-transform duration-700 ease-in-out group-hover/btn:scale-[20]" />
            <span className="relative z-10 transition-colors duration-500 group-hover/btn:text-gray-950 dark:group-hover/btn:text-white">
              Buy Now
            </span>
          </Button>
        </CardFooter>

      </Card>
    </div>
  );
}

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
<Card className="... group/card">
  <img className="... group-hover/card:scale-105" />

// Button-level hover: triggers the ripple animation
  <Button className="... group/btn">
    <span className="... group-hover/btn:scale-[20]" />

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

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

npx shadcn@latest add @shadcn-space/<identifier>

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:

1. Preview Card: group hover image animation, overflow clipping, and a logical border amenity row

2. Analytics Card: typed props with default data, conditional badge colors with cn(), and an absolutely-positioned decorative image

3. Statistics Card: data-driven repeating layout, responsive flex columns, and automatic last-border removal with last:

4. 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

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:

1. Installing the badge-07 component from Shadcn Space using the Shadcn CLI

2. Using motion.create() to wrap the shadcn/ui Badge into an animatable component

3. Adding layered radial-gradient glow effects as absolutely positioned spans

4. Animating the check icon with a scale and rotate entrance

5. Animating each letter of the label individually using staggered variants

Table of Contents

• 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 (
    <MotionBadge
      variant="outline"
      className={cn(
        "relative h-auto cursor-default overflow-visible rounded-full",
        "gap-2 px-3 py-2",
        "bg-background backdrop-blur-md",
        "text-foreground text-sm font-medium leading-none",
        "border-teal-400/25",
      )}
    >
      {/* Top glow */}
      <motion.span
        aria-hidden
        animate={{ opacity: 0.55 }}
        transition={{ duration: 0.45 }}
        className="pointer-events-none absolute -top-2 left-[10%] right-[10%] h-4 blur bg-[radial-gradient(ellipse_80%_100%_at_50%_100%,rgba(45,212,191,0.95)_0%,transparent_70%)]"
      />
      <motion.span
        aria-hidden
        animate={{ opacity: 0.75 }}
        transition={{ duration: 0.45 }}
        className="pointer-events-none absolute -top-1 left-[22%] right-[22%] h-2 blur-sm bg-[radial-gradient(ellipse_70%_100%_at_50%_100%,rgba(45,212,191,0.85)_0%,transparent_70%)]"
      />
      <motion.span
        aria-hidden
        animate={{ opacity: 0.9 }}
        transition={{ duration: 0.45 }}
        className="pointer-events-none absolute top-0 left-[28%] right-[28%] h-px bg-[radial-gradient(ellipse_40%_50%_at_50%_50%,rgba(45,212,191,0.95)_0%,transparent_100%)]"
      />

      {/* Icon */}
      <motion.span
        initial={{ scale: 0.35, opacity: 0, rotate: -25 }}
        animate={{ scale: 1, opacity: 1, rotate: 0 }}
        transition={{ duration: 0.32, ease: [0.175, 0.885, 0.32, 1.275] }}
        className="flex h-4 w-4 shrink-0 items-center justify-center"
      >
        <CheckCircle size={16} strokeWidth={2} className="text-teal-400" />
      </motion.span>

      {/* Animated label */}
      <span className="inline-flex overflow-hidden leading-none">
        {label.split("").map((char, i) => (
          <motion.span
            key={i}
            custom={i}
            variants={LETTER_VARIANTS}
            initial="hidden"
            animate="visible"
            className="inline-block whitespace-pre"
          >
            {char}
          </motion.span>
        ))}
      </span>
    </MotionBadge>
  );
};

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

<motion.span
  aria-hidden
  animate={{ opacity: 0.55 }}
  transition={{ duration: 0.45 }}
  className="pointer-events-none absolute -top-2 left-[10%] right-[10%] h-4 blur bg-[radial-gradient(ellipse_80%_100%_at_50%_100%,rgba(45,212,191,0.95)_0%,transparent_70%)]"
/>
<motion.span
  aria-hidden
  animate={{ opacity: 0.75 }}
  transition={{ duration: 0.45 }}
  className="pointer-events-none absolute -top-1 left-[22%] right-[22%] h-2 blur-sm bg-[radial-gradient(ellipse_70%_100%_at_50%_100%,rgba(45,212,191,0.85)_0%,transparent_70%)]"
/>
<motion.span
  aria-hidden
  animate={{ opacity: 0.9 }}
  transition={{ duration: 0.45 }}
  className="pointer-events-none absolute top-0 left-[28%] right-[28%] h-px bg-[radial-gradient(ellipse_40%_50%_at_50%_50%,rgba(45,212,191,0.95)_0%,transparent_100%)]"
/>

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

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

<motion.span
  initial={{ scale: 0.35, opacity: 0, rotate: -25 }}
  animate={{ scale: 1, opacity: 1, rotate: 0 }}
  transition={{ duration: 0.32, ease: [0.175, 0.885, 0.32, 1.275] }}
  className="flex h-4 w-4 shrink-0 items-center justify-center"
>
  <CheckCircle size={16} strokeWidth={2} className="text-teal-400" />
</motion.span>

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

<span className="inline-flex overflow-hidden leading-none">
  {label.split("").map((char, i) => (
    <motion.span
      key={i}
      custom={i}
      variants={LETTER_VARIANTS}
      initial="hidden"
      animate="visible"
      className="inline-block whitespace-pre"
    >
      {char}
    </motion.span>
  ))}
</span>

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 (
    <div className="flex items-center justify-center min-h-screen">
      <SuccessBadgeDemo />
    </div>
  );
}

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 (
    <MotionBadge
      variant="outline"
      className={cn(
        "relative h-auto cursor-default overflow-visible rounded-full",
        "gap-2 px-3 py-2",
        "bg-background backdrop-blur-md",
        "text-foreground text-sm font-medium leading-none",
        "border-blue-400/25",
      )}
    >
      <motion.span aria-hidden animate={{ opacity: 0.55 }} transition={{ duration: 0.45 }}
        className="pointer-events-none absolute -top-2 left-[10%] right-[10%] h-4 blur bg-[radial-gradient(ellipse_80%_100%_at_50%_100%,rgba(96,165,250,0.95)_0%,transparent_70%)]"
      />
      <motion.span aria-hidden animate={{ opacity: 0.75 }} transition={{ duration: 0.45 }}
        className="pointer-events-none absolute -top-1 left-[22%] right-[22%] h-2 blur-sm bg-[radial-gradient(ellipse_70%_100%_at_50%_100%,rgba(96,165,250,0.85)_0%,transparent_70%)]"
      />
      <motion.span aria-hidden animate={{ opacity: 0.9 }} transition={{ duration: 0.45 }}
        className="pointer-events-none absolute top-0 left-[28%] right-[28%] h-px bg-[radial-gradient(ellipse_40%_50%_at_50%_50%,rgba(96,165,250,0.95)_0%,transparent_100%)]"
      />

      <motion.span
        initial={{ scale: 0.35, opacity: 0, rotate: -25 }}
        animate={{ scale: 1, opacity: 1, rotate: 0 }}
        transition={{ duration: 0.32, ease: [0.175, 0.885, 0.32, 1.275] }}
        className="flex h-4 w-4 shrink-0 items-center justify-center"
      >
        <ShieldCheck size={16} strokeWidth={2} className="text-blue-400" />
      </motion.span>

      <span className="inline-flex overflow-hidden leading-none">
        {label.split("").map((char, i) => (
          <motion.span key={i} custom={i} variants={LETTER_VARIANTS}
            initial="hidden" animate="visible" className="inline-block whitespace-pre"
          >
            {char}
          </motion.span>
        ))}
      </span>
    </MotionBadge>
  );
};

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

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

Building a sidebar from scratch involves much more than an <nav> 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

Table of Contents

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

1. Floating sidebar shell: a card-style sidebar with rounded corners, a drop shadow, and a configurable width

2. Grouped navigation: navigation items organized under section labels like Dashboards, Pages, Apps, and Form Elements

3. Collapsible submenus: parent items like Blogs and Shadcn Forms that expand on click to reveal child links

4. Active state tracking: visual highlighting of the selected parent and child item at all times

5. Sidebar toggle: a trigger button in the page header that opens and closes the sidebar

6. 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",
    }
  }
}

How to Install the Sidebar Block

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 (
    <SidebarProvider
      className="p-4 bg-muted"
      style={{ "--sidebar-width": "300px" } as React.CSSProperties}
    >
      <AppSidebar />

      {/* Main content area */}
      <div className="flex flex-1 flex-col gap-4">
        <header className="flex h-14 shrink-0 items-center gap-2 rounded-xl bg-background px-4 shadow-sm">
          <SidebarTrigger className="cursor-pointer" />
        </header>
        <main className="flex-1 rounded-xl bg-background" />
      </div>
    </SidebarProvider>
  );
};

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.

How to Define the Navigation Data

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

1. A section label marked with isSection: true and a label string. Renders as an uppercase group heading.

2. A leaf item has a title, icon, and href, but no children. Renders as a direct navigation link.

3. 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<string | null>(
    items.find((i) => !i.isSection)?.title || null
  );
  const [activeChild, setActiveChild] = React.useState<string | null>(null);

  return (
    <>
      {items.map((item, index) => (
        <NavMainItem
          key={item.title || item.label || index}
          item={item}
          activeParent={activeParent}
          setActiveParent={setActiveParent}
          activeChild={activeChild}
          setActiveChild={setActiveChild}
        />
      ))}
    </>
  );
}

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 (
    <SidebarGroup className="p-0 pt-5 first:pt-0">
      <SidebarGroupLabel className="p-0 text-xs font-medium uppercase text-sidebar-foreground">
        {item.label}
      </SidebarGroupLabel>
    </SidebarGroup>
  );
}

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 (
    <SidebarGroup className="p-0">
      <SidebarMenu>
        <Collapsible open={isOpen} onOpenChange={setIsOpen}>
          <SidebarMenuItem>
            <CollapsibleTrigger
              className="w-full"
              render={
                <SidebarMenuButton
                  id={`nav-main-trigger-${item.title.toLowerCase().replace(/\s+/g, '-')}`}
                  tooltip={item.title}
                  isActive={isParentActive}
                  onClick={() => 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.icon size={16} />}
                  <span>{item.title}</span>
                  <ChevronRight
                    className={cn(
                      "ml-auto transition-transform duration-200",
                      isOpen && "rotate-90"
                    )}
                  />
                </SidebarMenuButton>
              }
            />
            <CollapsibleContent>
              <SidebarMenuSub className="me-0 pe-0">
                {item.children!.map((child, index) => (
                  <NavMainSubItem
                    key={child.title || index}
                    item={child}
                    activeParent={activeParent}
                    setActiveParent={setActiveParent}
                    activeChild={activeChild}
                    setActiveChild={setActiveChild}
                    parentTitle={item.title}
                  />
                ))}
              </SidebarMenuSub>
            </CollapsibleContent>
          </SidebarMenuItem>
        </Collapsible>
      </SidebarMenu>
    </SidebarGroup>
  );
}

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:

<ChevronRight
  className={cn(
    "ml-auto transition-transform duration-200",
    isOpen && "rotate-90"
  )}
/>

How to Render Leaf Items

if (item.title) {
  return (
    <SidebarGroup className="p-0">
      <SidebarMenu>
        <SidebarMenuItem>
          <SidebarMenuButton
            id={`nav-main-button-${item.title.toLowerCase().replace(/\s+/g, '-')}`}
            tooltip={item.title}
            isActive={isParentActive}
            onClick={() => {
              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={<a href={item.href} />}
          >
            {item.icon && <item.icon />}
            {item.title}
          </SidebarMenuButton>
        </SidebarMenuItem>
      </SidebarMenu>
    </SidebarGroup>
  );
}

The render prop on SidebarMenuButton replaces the default button element with an <a> 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 (
    <SidebarMenuSubItem className="w-full">
      <SidebarMenuSubButton
        id={`nav-sub-button-${item.title.toLowerCase().replace(/\s+/g, '-')}`}
        className={cn(
          "w-full rounded-md transition-colors",
          activeChild === item.title ? "bg-muted! text-foreground!" : ""
        )}
        isActive={activeChild === item.title}
        onClick={() => {
          setActiveParent(parentTitle || "");
          setActiveChild(item.title!);
        }}
        render={<a href={item.href}>{item.title}</a>}
      />
    </SidebarMenuSubItem>
  );
}

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.

How to Style the Sidebar

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

export function AppSidebar() {
  return (
    <Sidebar variant="floating" className="p-4 h-full [&_[data-slot=sidebar-inner]]:h-full">
      <div className="flex flex-col gap-6 overflow-hidden">

        {/* Header with Logo */}
        <SidebarHeader className="px-4">
          <SidebarMenu>
            <SidebarMenuItem>
              <a href="#" className="w-full h-full">
                <Logo />
              </a>
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarHeader>

        {/* Scrollable Navigation Content */}
        <SidebarContent className="overflow-hidden">
          <ScrollArea className="h-[calc(100vh-100px)]">
            <div className="px-4">
              <NavMain items={navData} />
            </div>

            {/* Promotional Card */}
            <div className="pt-5 px-4">
              <Card className="shadow-none ring-0 bg-secondary px-4 py-6">
                <CardContent className="p-0 flex flex-col gap-3 items-center">
                  <img
                    src="https://images.shadcnspace.com/assets/backgrounds/download-img.png"
                    alt="sidebar-img"
                    width={74}
                    height={74}
                    className="h-20 w-20"
                  />
                  <div className="flex flex-col gap-4 items-center">
                    <div>
                      <p className="text-base font-semibold text-card-foreground text-center">
                        Grab Pro Now
                      </p>
                      <p className="text-sm font-regular text-muted-foreground text-center">
                        Customize your admin
                      </p>
                    </div>
                    <Button className="w-fit h-9 px-4 py-2 shadow-none cursor-pointer rounded-xl hover:bg-primary/80">
                      Get Premium
                    </Button>
                  </div>
                </CardContent>
              </Card>
            </div>
          </ScrollArea>
        </SidebarContent>

      </div>
    </Sidebar>
  );
}

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

• Shadcn UI Blocks

• Shadcn UI Components

• Shadcn Space Getting Started Docs

• Figma UI Kit Design System

• shadcn/ui Sidebar Docs

• Base UI

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 <Tabs/> 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:

Table of Contents

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

1. 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.

2. Stacked card effect – inactive tab panels are rendered behind the active one, scaled down and slightly faded, giving a layered depth illusion.

3. Fan-out on hover – when the user hovers over the content area, the stacked cards spread out vertically.

4. 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: (
      <div className="w-full overflow-hidden relative rounded-2xl p-10 text-xl md:text-4xl font-bold text-foreground bg-muted h-[300px] border border-border">
        <p>Product Tab</p>
      </div>
    ),
  },
  {title: "Services",
    value: "services",
    content: (
      <div className="w-full overflow-hidden relative rounded-2xl p-10 text-xl md:text-4xl font-bold text-foreground bg-muted h-[300px] border border-border">
        <p>Services tab</p>
      </div>
    ),
  },
  {
    title: "Playground",
    value: "playground",
    content: (
      <div className="w-full overflow-hidden relative rounded-2xl p-10 text-xl md:text-4xl font-bold text-foreground bg-muted h-[300px] border border-border">
        <p>Playground tab</p>
      </div>
    ),
  },
 {
    title: "Content",
    value: "content",
    content: (
      <div className="w-full overflow-hidden relative rounded-2xl p-10 text-xl md:text-4xl font-bold text-foreground bg-muted h-[300px] border border-border">
        <p>Content tab</p>
      </div>
    ),
  },
  {
    title: "Random",
    value: "random",
    content: (
      <div className="w-full overflow-hidden relative rounded-2xl p-10 text-xl md:text-4xl font-bold text-foreground bg-muted h-[300px] border border-border">
        <p>Random tab</p>
      </div>
    ),
  },
];

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 (
    <>
      <div
        className={cn(
          "flex flex-row items-center justify-start [perspective:1000px] relative overflow-auto sm:overflow-visible no-visible-scrollbar max-w-full w-full",
          containerClassName,
        )}
      >
        {tabs.map((tab, idx) => {
          const isActive = idx === activeIdx;
          return (
            <button
            key={tab.value}
              onClick={() => handleSelect(idx)}
              onMouseEnter={() => setHovering(true)}
              onMouseLeave={() => setHovering(false)}
              className={cn("relative px-4 py-2 rounded-full", tabClassName)}
              style={{ transformStyle: "preserve-3d" }}
            >
              {isActive && (
                <motion.div
                  layoutId="clickedbutton"
                  transition={{ type: "spring", bounce: 0.3, duration: 0.6 }}
                  className={cn(
                    "absolute inset-0 bg-primary rounded-full",
                    activeTabClassName,
                  )}
                />
              )}
<span
                className={cn(
                  "relative block text-sm",
                  isActive ? "text-background": "text-foreground",
                )}
              >
                {tab.title}
              </span>
            </button>
          );
        })}
      </div>
      <FadeInStack
        tabs={reorderedTabs}
        hovering={hovering}
        className={cn("mt-10", contentClassName)}
      />
    </>
  );
};

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

const FadeInStack = ({ className, tabs, hovering }: FadeInStackProps) => {
  return (
    <div className="relative w-full h-[300px]">
      {tabs.map((tab, idx) => (
        <motion.div
          key={tab.value}
          layoutId={tab.value}
          style={{
            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,
          }}
          className={cn("w-full h-full absolute top-0 left-0", className)}
        >
          {tab.content}
        </motion.div>
      ))}
    </div>
  );
};

export default function AnimatedTabMotion() {
  return (
    <>
      <div className="[perspective:1000px] relative flex flex-col max-w-5xl mx-auto w-full items-start justify-start mb-13">
        <Tabs tabs={tabs} />
      </div>
    </>
  );

}

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 <div> 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 (
   <button
    key={tab.value}
    onClick={() => handleSelect(idx)}
    onMouseEnter={() => setHovering(true)}
    onMouseLeave={() => setHovering(false)}
    className={cn(“relative px-4 py-2 rounded-full”, tabClassName)}
    style={{ transformStyle: “preserve-3d” }}
    >
    {isActive && (
       <motion.div
        layoutId=“clickedbutton”
        transition={{ type: “spring”, bounce: 0.3, duration: 0.6 }}
        className={cn(
        “absolute inset-0 bg-primary rounded-full”,
        activeTabClassName,
     )}
   />
)}
<span
    className={cn(
        “relative block text-sm”,
        isActive ? “text-background” : “text-foreground”,
    )}
    >
      {tab.title}
     </span>
  </button>
);
})}

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 (
    <div className="relative w-full h-[300px]">
      {tabs.map((tab, idx) => (
        <motion.div
          key={tab.value}
          layoutId={tab.value}
          style={{
            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,
          }}
          className={cn("w-full h-full absolute top-0 left-0", className)}
        >
          {tab.content}
        </motion.div>
      ))}
    </div>
  );
};

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 (
    <div className="[perspective:1000px] relative flex flex-col max-w-5xl mx-auto w-full items-start justify-start mb-13">
      <Tabs tabs={tabs} />
    </div>
  );
}

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:

<Tabs
  tabs={tabs}
  containerClassName="gap-1"
  tabClassName="text-xs px-3 py-1.5"
  activeTabClassName="bg-zinc-900 dark:bg-white"
  contentClassName="mt-6"
/>

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: (
      <div className="w-full rounded-2xl p-8 bg-muted border border-border h-[300px] flex flex-col gap-4">
        <h2 className="text-2xl font-bold text-foreground">Product Overview</h2>
        <p className="text-muted-foreground text-sm leading-relaxed">
          Our platform helps teams ship faster with a fully integrated design-to-code workflow.
        </p>
      </div>
    ),
  },
  // ...
];

Live Preview

Key Concepts Recap

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

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

• Shadcn Space Tabs Component

• Shadcn Space Getting Started Guide

• Framer Motion Documentation

• Shadcn/ui Documentation

• Video Tutorial on YouTube

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

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

Table of Contents

1. Why TanStack Start?

2. Why shadcn/ui?

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

   • 1. Create a new TanStack app

   • 2. Initial Cleanup

   • 3. Setting Up shadcn/studio Blocks

   • 4. Routing Structure for the Dashboard

   • 5. Creating the /dashboard Layout

   • 6. Building the Dashboard Home Page

   • 7. Set up the Products Page.

   • 8. Settings Page

4. Live Demo & Source Code

5. 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:

1. Dashboard overview: A home page that displays various charts showing sales metrics, product insights widgets, and a transaction history table.

2. Products: A product page that demonstrates data fetching, server-side pagination, and advanced table features like column searching, sorting, and column filtering.

3. 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:

1. Remove the demo folder inside the src/routes directory (or wherever your router directory lives).

2. Delete Header.tsx from src/components.

3. Remove the Header import and usage from src/routes/__root.tsx.

4. 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 (
        <div className='flex min-h-dvh w-full'>
            <SidebarProvider>
                <Sidebar>
                    <SidebarContent>
                        <SidebarHeader>
                            <SidebarMenu>
                                <SidebarMenuItem>
                                    <SidebarMenuButton size="lg" asChild>
                                        <Link to="/">
                                            <div className="flex aspect-square size-8 items-center justify-center rounded-lg bg-primary text-primary-foreground">
                                                <User2 className="size-4" />
                                            </div>
                                            <div className="grid flex-1 text-left text-sm leading-tight">
                                                <span className="truncate font-semibold">Your App</span>
                                                <span className="truncate text-xs">Dashboard</span>
                                            </div>
                                        </Link>
                                    </SidebarMenuButton>
                                </SidebarMenuItem>
                            </SidebarMenu>
                        </SidebarHeader>

                        <SidebarGroup>
                            <SidebarGroupLabel>General</SidebarGroupLabel>
                            <SidebarGroupContent>
                                <SidebarMenu>
                                    <SidebarMenuItem>
                                        <SidebarMenuButton asChild>
                                            <Link to='/dashboard'>
                                                <LayoutDashboard />
                                                <span>Dashboard</span>
                                            </Link>
                                        </SidebarMenuButton>
                                    </SidebarMenuItem>
                                    <SidebarMenuItem>
                                        <SidebarMenuButton asChild>
                                            <Link to='/dashboard/products'>
                                                <Package />
                                                <span>Products</span>
                                            </Link>
                                        </SidebarMenuButton>
                                    </SidebarMenuItem>
                                    <SidebarMenuItem>
                                        <SidebarMenuButton asChild>
                                            <Link to='/dashboard/settings'>
                                                <Settings />
                                                <span>Settings</span>
                                            </Link>
                                        </SidebarMenuButton>
                                    </SidebarMenuItem>
                                </SidebarMenu>
                            </SidebarGroupContent>
                        </SidebarGroup>
                    </SidebarContent>
                </Sidebar>
                <div className='flex flex-1 flex-col'>
                    <header className='bg-card sticky top-0 z-50 border-b'>
                        <div className='mx-auto flex max-w-7xl items-center justify-between gap-6 px-4 py-2 sm:px-6'>
                            <div className='flex items-center gap-4'>
                                <SidebarTrigger className='[&_svg]:h-5 [&_svg]:w-5' />
                                <Separator orientation='vertical' className='hidden h-4 sm:block' />
                                <Breadcrumb className='hidden sm:block'>
                                    <BreadcrumbList>
                                        <BreadcrumbItem>
                                            <BreadcrumbLink asChild>
                                                <Link to='/'>Home</Link>
                                            </BreadcrumbLink>
                                        </BreadcrumbItem>
                                        <BreadcrumbSeparator />
                                        {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 (
                                                <React.Fragment key={path}>
                                                    <BreadcrumbItem>
                                                        {isLast ? (
                                                            <BreadcrumbPage>{title}</BreadcrumbPage>
                                                        ) : (
                                                            <BreadcrumbLink asChild>
                                                                <Link to={path as any}>{title}</Link>
                                                            </BreadcrumbLink>
                                                        )}
                                                    </BreadcrumbItem>
                                                    {!isLast && <BreadcrumbSeparator />}
                                                </React.Fragment>
                                            )
                                        })}
                                    </BreadcrumbList>
                                </Breadcrumb>
                            </div>
                            <div className='flex items-center gap-1.5'>
                                <LanguageDropdown
                                    trigger={
                                        <Button variant='ghost' size='icon'>
                                            <LanguagesIcon />
                                        </Button>
                                    }
                                />
                                <ProfileDropdown
                                    trigger={
                                        <Button variant='ghost' size='icon' className='h-10 w-10'>
                                            <Avatar className='h-10 w-10 rounded-md'>
                                                <AvatarImage src='https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-1.png' />
                                            </Avatar>
                                        </Button>
                                    }
                                />
                            </div>
                        </div>
                    </header>
                    <main className='mx-auto w-full max-w-7xl flex-1 px-4 py-6 sm:px-6'>
                        <Outlet />
                    </main>
                    <footer>
                        <div className='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'>
                            <p className='text-sm text-center sm:text-left'>
                                {`©${new Date().getFullYear()}`}{' '}
                                <a href='#' className='text-primary'>
                                    TanStack Start
                                </a>
                                , Made for better web design
                            </p>
                            <div className='flex items-center gap-5'>
                                <a href='#'>
                                    <FacebookIcon className='h-4 w-4' />
                                </a>
                                <a href='#'>
                                    <InstagramIcon className='h-4 w-4' />
                                </a>
                                <a href='#'>
                                    <LinkedinIcon className='h-4 w-4' />
                                </a>
                                <a href='#'>
                                    <TwitterIcon className='h-4 w-4' />
                                </a>
                            </div>
                        </div>
                    </footer>
                </div>
            </SidebarProvider>
        </div>
    )
}

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

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

• Sidebar structure: The <Sidebar> component wraps our navigation menu. Inside, we use <SidebarMenu> and <SidebarMenuItem> to create navigation links. Each menu item uses TanStack Router's <Link> component for type-safe navigation. We also have a header set up in the <SidebarProvider>

• 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: <LanguageDropdown> for internationalization and <ProfileDropdown> for user account actions. These come from the shadcn/studio blocks we installed.

• Outlet component: The <Outlet /> 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: <TruckIcon className='h-4 w-4' />,
        value: '42',
        title: 'Shipped Orders',
        changePercentage: '+18.2%'
    },
    {
        icon: <TriangleAlertIcon className='h-4 w-4' />,
        value: '8',
        title: 'Damaged Returns',
        changePercentage: '-8.7%'
    },
    {
        icon: <CalendarX2Icon className='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 (
        <div className='grid grid-cols-2 gap-6 lg:grid-cols-3'>
            {/* Statistics Cards */}
            <div className='col-span-full grid gap-6 sm:grid-cols-3 md:max-lg:grid-cols-1'>
                {StatisticsCardData.map((card, index) => (
                    <StatisticsCard
                        key={index}
                        icon={card.icon}
                        title={card.title}
                        value={card.value}
                        changePercentage={card.changePercentage}
                    />
                ))}
            </div>

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

                {/* Total Earning Card */}
                <TotalEarningCard
                    title='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'
                />
            </div>

            <SalesMetricsCard className='col-span-full xl:col-span-2 *:data-[slot=card-content]:space-y-6' />
            <Card className='col-span-full w-full py-0'>
                <TransactionDatatable data={transactionData} />
            </Card>
        </div>
    )
}

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 <SalesMetricsCard> 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 <TransactionDatatable> 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<Product>[] = [
    {
        accessorKey: 'name',
        header: ({ column }) => {
            return (
                <Button
                    variant="ghost"
                    onClick={() => column.toggleSorting(column.getIsSorted() === "asc")}
                >
                    Product Name
                    <ArrowUpDown className="ml-2 h-4 w-4" />
                </Button>
            )
        },
        cell: ({ row }) => (
            <div className="flex items-center gap-3">
                <img
                    src={row.original.image}
                    alt={row.getValue('name')}
                    className="h-10 w-10 rounded-md object-cover"
                />
                <div className="flex flex-col">
                    <span className="font-medium">{row.getValue('name')}</span>
                    <span className="text-xs text-muted-foreground">{row.original.id}</span>
                </div>
            </div>
        ),
    },
    {
        accessorKey: 'category',
        header: 'Category',
        cell: ({ row }) => <div>{row.getValue('category')}</div>,
    },
    {
        accessorKey: 'status',
        header: 'Status',
        cell: ({ row }) => {
            const status = row.getValue('status') as string
            return (
                <Badge variant={status === 'active' ? 'default' : status === 'draft' ? 'secondary' : 'outline'}>
                    {status}
                </Badge>
            )
        },
    },
    {
        accessorKey: 'price',
        header: () => <div className="text-right">Price</div>,
        cell: ({ row }) => {
            const amount = parseFloat(row.getValue('price'))
            const formatted = new Intl.NumberFormat('en-US', {
                style: 'currency',
                currency: 'USD',
            }).format(amount)

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

            return (
                <DropdownMenu>
                    <DropdownMenuTrigger asChild>
                        <Button variant="ghost" className="h-8 w-8 p-0">
                            <span className="sr-only">Open menu</span>
                            <MoreHorizontal className="h-4 w-4" />
                        </Button>
                    </DropdownMenuTrigger>
                    <DropdownMenuContent align="end">
                        <DropdownMenuLabel>Actions</DropdownMenuLabel>
                        <DropdownMenuItem
                            onClick={() => navigator.clipboard.writeText(product.id)}
                        >
                            Copy Product ID
                        </DropdownMenuItem>
                        <DropdownMenuSeparator />
                        <DropdownMenuItem>Edit Product</DropdownMenuItem>
                        <DropdownMenuItem>View Details</DropdownMenuItem>
                    </DropdownMenuContent>
                </DropdownMenu>
            )
        },
    },
]

function ProductsPage() {
    const [sorting, setSorting] = useState<SortingState>([])
    const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
    const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({})
    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 (
        <div className="w-full space-y-4">
            <div className="flex items-center justify-between">
                <h2 className="text-2xl font-bold tracking-tight">Products</h2>
                <div className="flex items-center gap-2">
                    <Button variant="outline" size="sm">
                        <Filter className="mr-2 h-4 w-4" />
                        Filter
                    </Button>
                    <Button size="sm">
                        <Plus className="mr-2 h-4 w-4" />
                        Add Product
                    </Button>
                </div>
            </div>

            <Card>
                <CardHeader>
                    <CardTitle>Product Management</CardTitle>
                    <CardDescription>
                        Manage your product catalog, track inventory, and update prices.
                    </CardDescription>
                </CardHeader>
                <CardContent>
                    <div className="flex items-center py-4 gap-2">
                        <div className="relative flex-1">
                            <Search className="absolute left-2 top-2.5 h-4 w-4 text-muted-foreground" />
                            <Input
                                placeholder="Filter products..."
                                value={(table.getColumn("name")?.getFilterValue() as string) ?? ""}
                                onChange={(event) =>
                                    table.getColumn("name")?.setFilterValue(event.target.value)
                                }
                                className="pl-8 max-w-sm"
                            />
                        </div>
                        <DropdownMenu>
                            <DropdownMenuTrigger asChild>
                                <Button variant="outline" className="ml-auto">
                                    Columns <ChevronDown className="ml-2 h-4 w-4" />
                                </Button>
                            </DropdownMenuTrigger>
                            <DropdownMenuContent align="end">
                                {table
                                    .getAllColumns()
                                    .filter((column) => column.getCanHide())
                                    .map((column) => {
                                        return (
                                            <DropdownMenuCheckboxItem
                                                key={column.id}
                                                className="capitalize"
                                                checked={column.getIsVisible()}
                                                onCheckedChange={(value) =>
                                                    column.toggleVisibility(!!value)
                                                }
                                            >
                                                {column.id}
                                            </DropdownMenuCheckboxItem>
                                        )
                                    })}
                            </DropdownMenuContent>
                        </DropdownMenu>
                    </div>
                    <div className="rounded-md border">
                        <Table>
                            <TableHeader>
                                {table.getHeaderGroups().map((headerGroup) => (
                                    <TableRow key={headerGroup.id}>
                                        {headerGroup.headers.map((header) => {
                                            return (
                                                <TableHead key={header.id}>
                                                    {header.isPlaceholder
                                                        ? null
                                                        : flexRender(
                                                            header.column.columnDef.header,
                                                            header.getContext()
                                                        )}
                                                </TableHead>
                                            )
                                        })}
                                    </TableRow>
                                ))}
                            </TableHeader>
                            <TableBody>
                                {isLoading ? (
                                    <TableRow>
                                        <TableCell colSpan={columns.length} className="h-24 text-center">
                                            <div className="flex items-center justify-center gap-2">
                                                <Loader2 className="h-6 w-6 animate-spin" />
                                                <span>Loading products...</span>
                                            </div>
                                        </TableCell>
                                    </TableRow>
                                ) : table.getRowModel().rows?.length ? (
                                    table.getRowModel().rows.map((row) => (
                                        <TableRow
                                            key={row.id}
                                            data-state={row.getIsSelected() && "selected"}
                                        >
                                            {row.getVisibleCells().map((cell) => (
                                                <TableCell key={cell.id}>
                                                    {flexRender(
                                                        cell.column.columnDef.cell,
                                                        cell.getContext()
                                                    )}
                                                </TableCell>
                                            ))}
                                        </TableRow>
                                    ))
                                ) : (
                                    <TableRow>
                                        <TableCell
                                            colSpan={columns.length}
                                            className="h-24 text-center"
                                        >
                                            No results.
                                        </TableCell>
                                    </TableRow>
                                )}
                            </TableBody>
                        </Table>
                    </div>
                    <div className="flex items-center justify-end space-x-2 py-4">
                        <div className="flex-1 text-sm text-muted-foreground">
                            {table.getFilteredSelectedRowModel().rows.length} of{" "}
                            {totalCount} row(s) selected.
                        </div>
                        <div className="space-x-2">
                            <Button
                                variant="outline"
                                size="sm"
                                onClick={() => table.previousPage()}
                                disabled={!table.getCanPreviousPage()}
                            >
                                Previous
                            </Button>
                            <Button
                                variant="outline"
                                size="sm"
                                onClick={() => table.nextPage()}
                                disabled={!table.getCanNextPage()}
                            >
                                Next
                            </Button>
                        </div>
                    </div>
                </CardContent>
            </Card>
        </div>
    )
}

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 (
    <div className="space-y-6">
      <div>
        <h3 className="text-lg font-medium">Settings</h3>
        <p className="text-sm text-muted-foreground">
          Manage your account settings and set e-mail preferences.
        </p>
      </div>
      <Separator />

      <div className="grid gap-6">
        <Card>
          <CardHeader>
            <CardTitle>Profile</CardTitle>
            <CardDescription>
              This is how others will see you on the site.
            </CardDescription>
          </CardHeader>
          <CardContent className="space-y-4">
            <div className="flex items-center gap-4">
              <Avatar className="h-20 w-20">
                <AvatarImage src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-1.png" />
                <AvatarFallback>JD</AvatarFallback>
              </Avatar>
              <Button variant="outline">Change Avatar</Button>
            </div>
            <div className="space-y-1">
              <label htmlFor="username" className="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70">Username</label>
              <Input id="username" defaultValue="jdoe" />
            </div>
            <div className="space-y-1">
              <label htmlFor="email" className="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70">Email</label>
              <Input id="email" defaultValue="john.doe@example.com" />
            </div>
            <div className="space-y-1">
              <label htmlFor="bio" className="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70">Bio</label>
              <Input id="bio" placeholder="Tell us a little bit about yourself" />
            </div>
          </CardContent>
          <CardFooter>
            <Button>Save Changes</Button>
          </CardFooter>
        </Card>

        <Card>
          <CardHeader>
            <CardTitle>Notifications</CardTitle>
            <CardDescription>
              Configure how you receive notifications.
            </CardDescription>
          </CardHeader>
          <CardContent className="space-y-4">
            <div className="flex items-center justify-between rounded-lg border p-4">
              <div className="space-y-0.5">
                <label className="text-base font-medium">Communication emails</label>
                <p className="text-sm text-muted-foreground">
                  Receive emails about your account activity.
                </p>
              </div>
              {/* Toggle would go here, using a simple checkbox for now */}
              <Checkbox defaultChecked />
            </div>
            <div className="flex items-center justify-between rounded-lg border p-4">
              <div className="space-y-0.5">
                <label className="text-base font-medium">Marketing emails</label>
                <p className="text-sm text-muted-foreground">
                  Receive emails about new products, features, and more.
                </p>
              </div>
              <Checkbox />
            </div>
          </CardContent>
          <CardFooter>
            <Button variant="outline">Update Preferences</Button>
          </CardFooter>
        </Card>
      </div>
    </div>
  )
}

In this page, we have created two sections:

1. Profile Section

2. 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:

• TanStack Start Documentation

• TanStack Table Docs

• TanStack Query Docs

• Shadcn UI Components

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

Table of Contents:

• What is a Registry in shadcn?

• How to Create and Configure Your Registry

• Namespace System

• Authentication for Private Registries

• CLI Commands

• Dependency Resolution

• Error Handling

• Conclusion

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": "<https://ui.shadcn.com/schema/registry.json>",
  "name": "acme",
  "homepage": "<https://acme.com>",
  "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 <Button>Hello World</Button>
}

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": "<https://registry.acme.com/ui/{name}.json>",
    "@acme-docs": "<https://registry.acme.com/docs/{name}.json>",
    "@acme-ai": "<https://registry.acme.com/ai/{name}.json>",
    "@acme-internal": {
      "url": "<https://internal.acme.com/registry/{name}.json>",
      "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": "<https://api.github.com/repos/org/registry/contents/{name}.json>",
    "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": "<https://api.company.com/registry/{name}>",
    "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": "<https://registry.company.com/{name}.json>",
    "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": "<https://registry.example.com/{name}.json>",
    "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 <https://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.

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.

Table of Contents

• What is shadcn/ui?

• Why Use shadcn/ui for Dropdowns?

• Let’s Build a Dropdown Step-by-Step

  • Step 1: Start a New Project

  • Step 2: Add the Dropdown Menu Component

  • Step 3: Import What You Need

  • Step 4: Build a Simple Dropdown

  • Step 5: Make It Look Better

  • Step 6: Make It Work on All Screens

  • Step 7: Add Cool Icons

  • Step 8: It’s Already Accessible!

• 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

Let’s Build a Dropdown Step-by-Step

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

Step 2: Add the Dropdown Menu Component

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"

Step 4: Build a Simple Dropdown

Here’s a basic dropdown example:

export function ProfileMenu() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <button className="px-4 py-2 bg-primary text-white rounded">
          Open Menu
        </button>
      </DropdownMenuTrigger>
      <DropdownMenuContent className="w-56">
        <DropdownMenuLabel>My Account</DropdownMenuLabel>
        <DropdownMenuSeparator />
        <DropdownMenuItem>Profile</DropdownMenuItem>
        <DropdownMenuItem>Settings</DropdownMenuItem>
        <DropdownMenuItem>Log out</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

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:

<DropdownMenu>
        <DropdownMenuTrigger asChild>
          <button className="px-3 py-1.5 bg-primary text-white text-sm font-medium rounded-md hover:bg-primary/90 transition-colors">
            Open Menu
          </button>
        </DropdownMenuTrigger>
        <DropdownMenuContent className="w-52 border-gray-200 shadow-lg rounded-md space-y-0.5">
          <DropdownMenuLabel className="text-xs text-gray-500">
            My Account
          </DropdownMenuLabel>
          <DropdownMenuSeparator className="border-t border-gray-100" />
          <DropdownMenuItem className="px-3 py-1.5 text-sm text-gray-700 hover:bg-gray-100 rounded-md cursor-pointer transition-colors">
            Profile
          </DropdownMenuItem>
          <DropdownMenuItem className="px-3 py-1.5 text-sm text-gray-700 hover:bg-gray-100 rounded-md cursor-pointer transition-colors">
            Settings
          </DropdownMenuItem>
          <DropdownMenuItem className="px-3 py-1.5 text-sm text-red-600 hover:bg-red-50 rounded-md cur

Step 6: Make It Work on All Screens

Want your dropdown to be responsive? Use Tailwind’s responsive classes:

<DropdownMenuContent className="w-full md:w-64">

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"

<DropdownMenuItem>
  <User className="mr-2 h-4 w-4" /> Profile
</DropdownMenuItem>

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.

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).