DEV Community

A0mineTV
A0mineTV

Posted on

Integrating Shadcn/ui into Laravel 12

#laravel #php #webdev #productivity

Shadcn/ui is a collection of headless UI components built on Radix primitives and styled with Tailwind CSS. In this guide, we’ll walk through how to integrate Shadcn/ui into a Laravel 12 application using Inertia and React. By the end, you’ll have a working Laravel 12 project with Shadcn/ui components ready to use.

Table of Contents

  1. Prerequisites
  2. Create a New Laravel 12 Project
  3. Install React Starter Kit
  4. Configure Tailwind CSS
  5. Install Shadcn/ui Dependencies
  6. Initialize Shadcn/ui
  7. Use a Shadcn/ui Component
  8. Example: Building a Simple Card
  9. Conclusion

Prerequisites

Make sure you have the following installed:

  • PHP 8.2+
  • Composer
  • Node.js 16+ and npm (or Yarn)
  • Git
  • A code editor (e.g., VS Code)

This guide assumes a fresh environment. If you already have a Laravel 12 project with Inertia + React, you can skip to the Install Shadcn/ui Dependencies section.

Create a New Laravel 12 Project

Start by creating a new Laravel 12 application using Composer:

composer create-project laravel/laravel my-shadcn-app "12.*"
cd my-shadcn-app
Enter fullscreen mode Exit fullscreen mode

Next, make sure your .env file has the correct database configuration. You can skip database details if you only need front-end components; otherwise, set your DB connection now.

Install React Starter Kit

Laravel 12 ships with a built-in command to scaffold a React + Inertia starter kit. Run:

php artisan starter:install react
Enter fullscreen mode Exit fullscreen mode

This command will:

  • Install Inertia and React scaffolding.
  • Publish Inertia’s boilerplate in resources/js.
  • Set up a basic layout, routing, and example pages.

After the starter:install command finishes, install Node dependencies and compile assets:

npm install
npm run dev
Enter fullscreen mode Exit fullscreen mode

You should see a resources/js directory containing:

  • app.jsx (entrypoint)
  • Pages/ (folder for Inertia pages)
  • Layouts/ (default layout)

Now launch Laravel’s built-in server to verify everything works:

php artisan serve
Enter fullscreen mode Exit fullscreen mode

Visit http://127.0.0.1:8000 in your browser. You should see the default “Laravel + React” welcome page.

Configure Tailwind CSS

Shadcn/ui relies on Tailwind CSS. The React starter kit already includes Tailwind, but let’s double-check our configuration.

1- Install Tailwind CSS (if not already installed)

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
Enter fullscreen mode Exit fullscreen mode

2- Configure tailwind.config.js

In the project root, open tailwind.config.js and ensure the content array includes your React files:

module.exports = {
  content: [
    './resources/views/**/*.blade.php',
    './resources/js/**/*.jsx',
    './resources/js/**/*.js',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};
Enter fullscreen mode Exit fullscreen mode

3- Update resources/css/app.css

Make sure your app.css includes the Tailwind directives (the React starter does this by default):

@tailwind base;
@tailwind components;
@tailwind utilities;
Enter fullscreen mode Exit fullscreen mode

4- Verify Build

Re-run the asset build:

npm run dev
Enter fullscreen mode Exit fullscreen mode

If you see no Tailwind-related errors, you’re ready to install Shadcn/ui.

 Install Shadcn/ui Dependencies

Shadcn/ui components leverage Radix UI primitives under the hood. We need to install both Radix-related packages and the Shadcn/ui CLI.

1- Install Radix Core & Shadcn/ui packages:

npm install @radix-ui/react-hover-card @radix-ui/react-dialog @radix-ui/react-popover @radix-ui/react-tabs
npm install tailwind-merge tailwind-variants
Enter fullscreen mode Exit fullscreen mode

Note: The exact Radix packages you install depend on which components you plan to use. Common primitives include hover-card, dialog, popover, tabs, toolbar, etc. Adjust as needed.

2- Install the Shadcn/ui CLI:

npm install -D shadcn-ui
Enter fullscreen mode Exit fullscreen mode

The shadcn-ui package provides a CLI that automates component generation.

Initialize Shadcn/ui

With dependencies installed, we need to generate the configuration and component templates.

1- Run the Shadcn/ui init command:

npx shadcn-ui init
Enter fullscreen mode Exit fullscreen mode

This command will:

  • Create a components/ directory under resources/js.
  • Generate a tailwind.config.js snippet if needed (verify your existing file).
  • Create a shadcn.toml config file in the project root.

2- Verify shadcn.toml

Open shadcn.toml in your code editor. It looks like:

[project]
source = "resources/js/components"
Enter fullscreen mode Exit fullscreen mode

If you want to change where Shadcn/ui places its components, update the source path. The default of resources/js/components is fine for most cases.

Use a Shadcn/ui Component

Now that Shadcn/ui is initialized, let’s install a sample component, such as a “Card”.

1- Generate the Card component:

npx shadcn-ui add card
Enter fullscreen mode Exit fullscreen mode

This command will create:

resources/js/components/ui/card/
├── card.jsx
├── card.css
└── index.jsx
Enter fullscreen mode Exit fullscreen mode

The folder contains both the component logic (card.jsx) and styles (card.css). By default, Shadcn/ui components use Tailwind classes and tailwind-variants for styling.

2- Import the Card component

In your React application (e.g., /resources/js/Pages/Welcome.jsx), import and use the Card:

// resources/js/Pages/Welcome.jsx
import React from 'react';
import { Inertia } from '@inertiajs/inertia';
import Layout from '@/Layouts/Layout';
import { Card, CardHeader, CardContent } from '@/components/ui/card';

export default function Welcome() {
  return (
    <Layout>
      <div className="p-6">
        <h1 className="text-3xl font-bold mb-4">Welcome to Laravel 12 + Shadcn/ui</h1>
        <Card className="max-w-md">
          <CardHeader>
            <h2 className="text-xl font-semibold">Shadcn/ui Card</h2>
          </CardHeader>
          <CardContent>
            <p>This is an example of a Shadcn/ui Card component integrated into Laravel 12.</p>
          </CardContent>
        </Card>
      </div>
    </Layout>
  );
}
Enter fullscreen mode Exit fullscreen mode

Tip: The default Layout.jsx (in resources/js/Layouts/Layout.jsx) is generated by Inertia’s React starter and includes <Head> and <main> wrappers. You can customize it as needed.

3- Compile assets:

npm run dev
Enter fullscreen mode Exit fullscreen mode

4- View in Browser

With php artisan serve running, visit http://127.0.0.1:8000. You should see the Shadcn/ui Card rendered on the welcome page.

Example: Building a Simple Card with Shadcn/ui

Let’s dive deeper into the structure of a generated Shadcn/ui Card and see how to customize it.

1- Examine card.jsx

Open resources/js/components/ui/card/card.jsx:

import * as React from "react";
import { cn } from "@/lib/utils"; // utility to merge Tailwind classes

const Card = React.forwardRef(({ className, ...props }, ref) => {
  return (
    <div
      ref={ref}
      className={cn(
        "rounded-lg border bg-white shadow-sm",
        className
      )}
      {...props}
    />
  );
});
Card.displayName = "Card";

export { Card };
Enter fullscreen mode Exit fullscreen mode

And card.css:

.card {
  @apply p-4;
}
Enter fullscreen mode Exit fullscreen mode

Shadcn/ui uses a small cn helper (lib/utils.js) to merge conditional Tailwind classes. You can find it in resources/js/lib/utils.js:

// resources/js/lib/utils.js
export function cn(...classes) {
  return classes.filter(Boolean).join(" ");
}
Enter fullscreen mode Exit fullscreen mode

2- Customize Styles

If you want to adjust the default padding or shadow, edit card.jsx:

// resources/js/components/ui/card/card.jsx
import * as React from "react";
import { cn } from "@/lib/utils";

const Card = React.forwardRef(({ className, ...props }, ref) => {
  return (
    <div
      ref={ref}
-     className={cn(
-       "rounded-lg border bg-white shadow-sm",
-       className
-     )}
    className={cn(
      "rounded-xl border bg-gray-50 shadow-md hover:shadow-lg transition-shadow",
      className
    )}
    {...props}
  />
);
Card.displayName = "Card";

export { Card };
Enter fullscreen mode Exit fullscreen mode

Now your card will have a slightly different appearance (e.g., rounded-xl, bg-gray-50, hover effect).

3- Use in a Page

Update any Inertia page (e.g., Dashboard.jsx) to leverage the customized Card:

// resources/js/Pages/Dashboard.jsx
import React from "react";
import Layout from "@/Layouts/Layout";
import { Card, CardHeader, CardContent } from "@/components/ui/card";

export default function Dashboard() {
  return (
    <Layout>
      <div className="p-8 grid grid-cols-1 md:grid-cols-2 gap-6">
        <Card>
          <CardHeader>
            <h2 className="text-lg font-semibold">Card Title</h2>
          </CardHeader>
          <CardContent>
            <p>Some content inside the card.</p>
          </CardContent>
        </Card>

        <Card className="bg-white">
          <CardHeader>
            <h2 className="text-lg font-semibold">Another Card</h2>
          </CardHeader>
          <CardContent>
            <p>More content in a different card.</p>
          </CardContent>
        </Card>
      </div>
    </Layout>
  );
}
Enter fullscreen mode Exit fullscreen mode

 Conclusion

In this guide, we covered how to integrate Shadcn/ui into a Laravel 12 application using Inertia and React. We:

  • Created a fresh Laravel 12 project
  • Installed and configured the React starter kit
  • Set up Tailwind CSS
  • Installed Radix and Shadcn/ui dependencies
  • Initialized Shadcn/ui and generated a Card component
  • Customized and used the Shadcn/ui Card in an Inertia page

Shadcn/ui provides a suite of well-structured, headless components that you can tailor to your design system using Tailwind CSS. Now that you have the basics, explore other components (e.g., Dialog, Popover, Tabs) by running:

npx shadcn-ui add dialog
npx shadcn-ui add tabs
Enter fullscreen mode Exit fullscreen mode

Refer to Shadcn/ui’s documentation for a comprehensive list of available components and configuration options.

Top comments (0)