Installation

Learn how to install and integrate Franken UI in your projects.

Installation Via CDN

Perfect for beginners, the simplest installation can be done using CDN. Choose only one of 12 styles available in your <head> tag. Do not include two styles at once.

<link
  rel="stylesheet"
  href="https://unpkg.com/[email protected]/dist/css/slate.min.css"
/>
<link
  rel="stylesheet"
  href="https://unpkg.com/[email protected]/dist/css/stone.min.css"
/>
<link
  rel="stylesheet"
  href="https://unpkg.com/[email protected]/dist/css/gray.min.css"
/>
<link
  rel="stylesheet"
  href="https://unpkg.com/[email protected]/dist/css/neutral.min.css"
/>
<link
  rel="stylesheet"
  href="https://unpkg.com/[email protected]/dist/css/red.min.css"
/>
<link
  rel="stylesheet"
  href="https://unpkg.com/[email protected]/dist/css/rose.min.css"
/>
<link
  rel="stylesheet"
  href="https://unpkg.com/[email protected]/dist/css/orange.min.css"
/>
<link
  rel="stylesheet"
  href="https://unpkg.com/[email protected]/dist/css/green.min.css"
/>
<link
  rel="stylesheet"
  href="https://unpkg.com/[email protected]/dist/css/blue.min.css"
/>
<link
  rel="stylesheet"
  href="https://unpkg.com/[email protected]/dist/css/yellow.min.css"
/>
<link
  rel="stylesheet"
  href="https://unpkg.com/[email protected]/dist/css/violet.min.css"
/>
<link
  rel="stylesheet"
  href="https://unpkg.com/[email protected]/dist/css/zinc.min.css"
/>

Once you’re done, you may now proceed adding JavaScript.

Installation Via NPM

Because Franken UI is a Tailwind CSS plugin, it can be included into any existing Tailwind CSS project. To get started, you first need to make sure that you have a working Tailwind CSS project installed and that you also have Node and NPM installed on your machine.

1. Install PostCSS and the latest version of Franken UI using NPM:

npm install postcss franken-ui

2. Run the npx franken-ui init -p command.

npx franken-ui init -p

v0.1.0 This command will automatically generate and configure both tailwindcss.config.js and postcss.config.cjs for you.

If you want total control over the components used, you can pass the --fine flag (or its shorthand, -i). Alternatively, if you’re building your own theme and want to opt out of shadcn/ui, use the --raw flag (or its shorthand, -r). Note that you can only use one of these flags.

For example, this command will generate a fine-grained tailwind.config.js file along with a postcss.config.cjs file. If you only need the Tailwind CSS configuration, you can simply omit the -p flag.

npx franken-ui init -ip

Additionally, if you already have a Tailwind CSS or PostCSS configuration in place, the command will refuse to create a new one. This ensures that your existing configuration isn’t accidentally overwritten.

If you have trouble running the command, you can always refer to the source code and grab the right configuration you need.

3. Once you’re done, you may now proceed adding JavaScript.

Theming

Franken UI offers 12 variety of themes:

  • slate
  • stone
  • gray
  • neutral
  • red
  • rose
  • orange
  • green
  • blue
  • yellow
  • violet
  • zinc

To set a theme, configure your preset function to use your desired theme. Here’s an example using the green theme:

import franken from "franken-ui/shadcn-ui/preset-quick";

/** @type {import('tailwindcss').Config} */
export default {
  presets: [franken({ theme: "green" })],
};

Or, if you are using the fine-grained configuration, you can set the theme inside hooks() and variables() functions:

import variables from "franken-ui/shadcn-ui/variables";
import hooks from "franken-ui/shadcn-ui/hooks";

const shadcn = hooks({
  theme: "green",
});

/** @type {import('tailwindcss').Config} */
export default {
  plugins: [
    variables({
      theme: "green",
    }),
  ],
};

Custom Palette

If you find the 12 existing themes somewhat limiting, You can refer to this documentation on how to generate your own palette.

Picking Components

v0.1.0 For most cases, we only need a few components. You can select the components you need using fine-grained configuration by commenting on them. However, starting from version 0.1.x, you can now also do this in preset-quick and use the only and except options.

For example, if you only want the button, form, modal, and offcanvas components, you can configure it as follows:

import franken from "franken-ui/shadcn-ui/preset-quick";

/** @type {import('tailwindcss').Config} */
export default {
  presets: [
    franken({
      theme: "green",
      only: ["button", "form", "modal", "offcanvas"],
    }),
  ],
};

Please be aware that some components depend on others, which might cause issues. I have tried to resolve these dependencies as best as I could, and “safetynets” are in place, but there is a limit to what I can do. If you encounter any such issues and manage to resolve them on your own, please file a GitHub issue so we can improve our built-in resolver.

On the other hand, if you want all components but want to exclude a few, you can use the except option:

import franken from "franken-ui/shadcn-ui/preset-quick";

/** @type {import('tailwindcss').Config} */
export default {
  presets: [
    franken({
      theme: "green",
      except: ["align", "article", "margin", "padding"],
    }),
  ],
};

This will result in a leaner CSS build.

Customization

If there are specific styles you’d like to override, you can always utilize Tailwind CSS utility classes. For more advanced customization options, consider exploring the use of hooks.

Editor setup

Keeping track of hooks and configurations can be challenging, but with Franken UI’s TypeScript support and a good editor, you can benefit from autocomplete features. If you already have Tailwind CSS IntelliSense installed, you won’t need any additional plugins. This not only saves time but also eliminates the need to manually look up and type all classes.