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
- Prerequisites
- Create a New Laravel 12 Project
- Install React Starter Kit
- Configure Tailwind CSS
- Install Shadcn/ui Dependencies
- Initialize Shadcn/ui
- Use a Shadcn/ui Component
- Example: Building a Simple Card
- 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
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
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
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
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
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: [],
};
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;
4- Verify Build
Re-run the asset build:
npm run dev
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
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
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
This command will:
- Create a
components/
directory underresources/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"
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
This command will create:
resources/js/components/ui/card/
├── card.jsx
├── card.css
└── index.jsx
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>
);
}
Tip: The default
Layout.jsx
(inresources/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
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 };
And card.css:
.card {
@apply p-4;
}
Shadcn/ui uses a small
cn
helper (lib/utils.js
) to merge conditional Tailwind classes. You can find it inresources/js/lib/utils.js
:
// resources/js/lib/utils.js
export function cn(...classes) {
return classes.filter(Boolean).join(" ");
}
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 };
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>
);
}
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
Refer to Shadcn/ui’s documentation for a comprehensive list of available components and configuration options.
Top comments (0)