Skip to main content

Installation

How to get started with MateUI in your project.

Prerequisites
Before you begin, make sure you have installed:
  • React 18+ or Next.js 15+
  • TypeScript
  • Tailwind CSS v3+
  • Node.js 18+

Step-by-step installation

Set up Tailwind CSS

If you don't have Tailwind CSS installed yet, follow the official guide:

Install required dependencies

MateUI requires the following libraries to work properly:
npm install install motion clsx tailwind-merge class-variance-authority lucide-react
These libraries are used for:
  • motion: Smooth animations and transitions (Framer Motion)
  • clsx: Conditional CSS class construction
  • tailwind-merge: Smart merging of Tailwind classes
  • class-variance-authority: Component variant management
  • lucide-react: Icons used in components

Configure the cn function

Create a utility file for the cn function that will combine CSS classes:
lib/cn.ts
1import { clsx, type ClassValue } from 'clsx';
2import { twMerge } from 'tailwind-merge';
3 
4export function cn(...inputs: ClassValue[]) {
5  return twMerge(clsx(inputs));
6}
This function is used by all MateUI components to intelligently merge Tailwind classes.

Add CSS variables

Add the color variables to your global CSS file (typically globals.css or app.css):
1@import 'tailwindcss';
2@custom-variant dark (&:where(.dark, .dark *));
3 
4:root {
5  --background: oklch(99.405% 0.00011 271.152);
6  --foreground: oklch(0% 0 0);
7  --card: oklch(99.405% 0.00011 271.152);
8  --card-foreground: oklch(0% 0 0);
9  --popover: oklch(99.107% 0.00011 271.152);
10  --popover-foreground: oklch(0% 0 0);
11  --primary: oklch(53.934% 0.2714 286.753);
12  --primary-foreground: oklch(100% 0.00011 271.152);
13  --secondary: oklch(95.4% 0.00637 255.746);
14  --secondary-foreground: oklch(13.441% 0.00002 271.152);
15  --muted: oklch(97.015% 0.00011 271.152);
16  --muted-foreground: oklch(43.861% 0.00005 271.152);
17  --accent: oklch(93.929% 0.02887 266.393);
18  --accent-foreground: oklch(54.456% 0.19041 259.501);
19  --destructive: oklch(62.902% 0.19024 23.052);
20  --destructive-foreground: oklch(100% 0.00011 271.152);
21  --border: oklch(88.09% 0.00941 258.48);
22  --input: oklch(93.1% 0.00011 271.152);
23  --ring: oklch(0% 0 0);
24  --radius: 0.625rem;
25  --grid-color: oklch(0% 0 0 / 0.04);
26  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.03);
27  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.06), 0 2px 4px -2px rgb(0 0 0 / 0.06);
28  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.08), 0 4px 6px -4px rgb(0 0 0 / 0.08);
29}
30 
31.dark {
32  --background: oklch(12% 0.01 260);
33  --foreground: oklch(98% 0.002 270);
34  --card: oklch(15% 0.01 260);
35  --card-foreground: oklch(98% 0.002 270);
36  --popover: oklch(10% 0.012 260);
37  --popover-foreground: oklch(98% 0.002 270);
38  --primary: oklch(61.319% 0.22952 291.745);
39  --primary-foreground: oklch(100% 0.00011 271.152);
40  --secondary: oklch(29.399% 0.01304 272.934);
41  --secondary-foreground: oklch(95.514% 0.00011 271.152);
42  --muted: oklch(29.399% 0.01304 272.934);
43  --muted-foreground: oklch(70.576% 0.00008 271.152);
44  --accent: oklch(27.95% 0.03688 260.049);
45  --primary-foreground: oklch(100% 0.00011 271.152);
46  --destructive: oklch(71.061% 0.16614 22.191);
47  --destructive-foreground: oklch(100% 0.00011 271.152);
48  --border: oklch(22% 0.01 260);
49  --input: oklch(18% 0.01 260);
50  --ring: oklch(29.968% 0.01228 258.414);
51  --grid-color: oklch(100% 0 0 / 0.02);
52  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.5);
53  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.4), 0 2px 4px -2px rgb(0 0 0 / 0.4);
54  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.5), 0 4px 6px -4px rgb(0 0 0 / 0.5);
55}

Add variables to @theme

1@theme inline {
2  --color-background: var(--background);
3  --color-foreground: var(--foreground);
4  --color-card: var(--card);
5  --color-card-foreground: var(--card-foreground);
6  --color-popover: var(--popover);
7  --color-popover-foreground: var(--popover-foreground);
8  --color-primary: var(--primary);
9  --color-primary-foreground: var(--primary-foreground);
10  --color-secondary: var(--secondary);
11  --color-secondary-foreground: var(--secondary-foreground);
12  --color-muted: var(--muted);
13  --color-muted-foreground: var(--muted-foreground);
14  --color-accent: var(--accent);
15  --color-accent-foreground: var(--accent-foreground);
16  --color-destructive: var(--destructive);
17  --color-destructive-foreground: var(--destructive-foreground);
18  --color-border: var(--border);
19  --color-input: var(--input);
20  --color-ring: var(--ring);
21  --radius-sm: calc(var(--radius) - 0.25rem);
22  --radius-md: calc(var(--radius) - 0.125rem);
23  --radius-lg: var(--radius);
24  --radius-xl: calc(var(--radius) + 0.25rem);
25  --radius-2xl: calc(var(--radius) + 0.5rem);
26}

Recommended Project Structure

Here's the recommended folder structure for organizing MateUI components in your project:
src
components
ui
button.tsx
card.tsx
tabs.tsx
...
header.tsx
footer.tsx
package.json
tailwind.config.ts
tsconfig.json
Key directories:
  • components/ui/ - MateUI components (copied from docs)
  • lib/ - Utility functions like cn

How to use components

Once your project is configured, you can start copying components:
  1. Navigate to the component page you want to use
  2. Copy the component code
  3. Paste it into your project (typically in components/ui/)
  4. Adjust import paths if necessary
  5. Customize the component according to your needs

Next steps

PreviousComponentsNextTheming