Filigran-UI Installation and Setup for Tailwind CSS Projects

This tutorial will show you how to install Filigran-UI and integrate it with an existing Tailwind CSS setup, allowing you to use the full power of both libraries.

1. Install Filigran-UI

First, you need to install the Filigran-UI library. Run the following command to add it to your project:

npm install @filigran/ui

or if you're using yarn:

yarn add @filigran/ui

2. Configure Tailwind CSS v4 (CSS-first)

Tailwind CSS v4 uses the @tailwindcss/postcss plugin and CSS-first directives directly in your global CSS.

postcss.config.js

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

app/globals.css (or your global stylesheet)

@import "tailwindcss";
@import "@filigran/ui/theme.css";

/* Keep dark mode class-driven */
@custom-variant dark (&:where(.dark, .dark *));

/* Include classes coming from Filigran UI */
@source "@filigran/ui";

/* Default border color with Filigran theme tokens */
@layer utilities {
  .border,
  .border-x,
  .border-y,
  .border-t,
  .border-r,
  .border-b,
  .border-l {
    border-color: hsl(var(--border));
  }
}

/* Optional plugins */
@plugin "tailwindcss-animate";

This configuration allows your project to pick up all the styles and classes provided by Filigran-UI, while staying fully CSS-first in Tailwind v4.

3. Theme Import Note

No additional theme import is needed in app/layout.tsx because @filigran/ui/theme.css is already imported in app/globals.css.

4. Using Filigran-UI Components

Now that Filigran-UI is set up, you can start using the components in your React project alongside Tailwind CSS utilities. Here’s how to use a button component:

import {Button} from '@filigran/ui'

function App() {
  return (
    <div>
      <Button>Primary/Default</Button>
    </div>
  )
}

export default App

Since you’re using Tailwind, you can apply Tailwind’s utility classes alongside the Filigran-UI components to further customize the design.

5. Special Setup for Next.js or SSR

If your project is built using Next.js or requires Server-Side Rendering (SSR), you can take advantage of Filigran-UI’s optimized server and client components.

Server-Side Rendering Components To use components on the server, import from "@filigran/ui/servers":

import {Button} from '@filigran/ui/servers'

Client-Side Components For interactive components that need to run on the client, import from "@filigran/ui/clients":

import {Combobox} from '@filigran/ui/clients'

This ensures that your components are properly handled in Next.js or other SSR frameworks.

6. Conclusion

By following these steps, you’ve successfully installed and configured Filigran-UI in your Tailwind CSS project. You now have access to Filigran-UI’s powerful and flexible components while keeping the full capabilities of the Tailwind CSS system. You can further customize the components with Tailwind utilities as needed.

Feel free to explore more components and make use of the design system in your project to improve consistency and efficiency.