Paradigm

Traditional UI Libraries

• Pro: Good out of the box design.
• Con: Hard to customize because style is coupled to components.

Headless UI Primitives

• Pro: Flexibility in customization.
• Con: Extra work to theme and style.

The shadcn way

• shadcn is not a library you import into your code.
• Components are copied and pasted into your codebase.
• Provides sensible styling on top of Radix UI primitives and other libraries.
• A CLI tool to quickly copy and paste the components you need into your codebase.
• A starting point to build your own component library

Pros

Pro 1

• Customizations are easy.
• Why? Because code is copied and pasted into your source code.

Pro 2

• Minimal "lock in" to the library.
• How? Easy to replace underlying dependencies. (facade pattern).
• Example: Can change the underlying calendar dependency in the future.

Pro 3

• The theme is controlled by a global.css file instead of proprietary theme object.
• If you know CSS, then it's easy to change up the theme without looking at documentation.

Pro 4

• Less gotchas integrating with TailwindCSS than some other UI libraries

Cons

Con 1

• Updates might be hard to do.
• Update multiple dependencies instead of one.

Con 2

• Code base gets "cluttered" with extra files.
  • /components/ui/*
  • components.json
  • tailwind.config.ts
  • package.json
  • utils.ts

Con 3

• Takes a bit more setup than other UI libraries.
• Have to run the add command or manually copy and paste things.

Tips

Tip 1

• Use CSS Variables.
• Why? Easy to change global styles, color accents, etc in the future.

Tip 2

• Use CSS variables for custom fonts.
• Why? Same reason. Easy to change font in the future.

Tip 3

• Declare new color accents in global.css and tailwind.config.ts.
• Remember to declare both a base and dark style.
• Use the bg-variantname and text-variantname-foreground convention.

When to use?

• If you want sensible default styling on top of Radix UI primitives.
• If you want the increased flexibility to change things down the road.

When to not use?

• If you prefer the aesthetic of another "Traditional UI" library.
• If you are ok having less control over the styles and underlying dependencies.
• If you are ok being locked in to a UI library.