# Catppuccin for Tailwind CSS: a pastel palette as a set of utilities
> The catppuccin/tailwindcss package gives a Tailwind project the Catppuccin palette, and the detail that makes it more than a colour config file is the naming scheme, where every colour is prefixed with ctp so it cannot collide with Tailwind's own scale, and where four flavour variants exist as ordinary classes you can put on a container. The package reached 1.0 in July 2025 after two beta releases earlier the same year.
**catppuccin/tailwindcss** — 💨 Soothing pastel theme for Tailwind CSS
- Repository: https://github.com/catppuccin/tailwindcss
- Website: https://www.npmjs.com/package/@catppuccin/tailwindcss
- Stars: 534 · Forks: 18
- Language: SCSS
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/catppuccin-tailwindcss
## What the package is, and what the palette is
The repository is the Catppuccin flavour of Tailwind CSS, described as a soothing pastel theme for Tailwind CSS, and the primary language is recorded as SCSS.
Catppuccin is a community theme project rather than a single piece of software. It defines a palette of pastel colours and a set of flavour variants, and this repository is one of the ports that carry that palette into a particular tool. The README's header art points at the Catppuccin organisation and the palette's own assets, and the footer is the standard Catppuccin footer with the copyright line and the MIT licence badge for the Catppuccin Org.
The primary language being SCSS is worth noticing, because it tells you the colours arrive as stylesheets rather than as a Tailwind plugin written in JavaScript. The distribution is a set of CSS files, one per flavour, which you import after Tailwind's own import. That is the whole mechanism, and it is why there is no JavaScript in the package at all.
The primary language here is SCSS, the licence is MIT, the default branch is main, and the homepage is the npm page for @catppuccin/tailwindcss. The recent releases are v1.0.0 from 2025-07-26, v1.0.0-beta.2 and v1.0.0-beta.1 both from 2025-04-20, and the last push was on 2026-10-16 with the project not archived. The npm package is the distribution channel, with releases published as v1.0.0 and its two betas.
The two beta releases on the same day in April 2025, then a stable release three months later, is the usual shape for a package that had to change its output format on the way to 1.0.
The four flavours the README names are latte, frappe, macchiato and mocha, and the design decision is visible in the usage section: latte is the light flavour, and the other three are dark, with mocha recommended for dark mode. The README also points at a separate site with more advanced examples at tailwindcss.catppuccin.com.
## Installing it, and the three package managers
The usage section starts with the install, and it gives the command for all three major package managers in one block:
```sh
npm install -D @catppuccin/tailwindcss
pnpm add -D @catppuccin/tailwindcss
yarn add -D @catppuccin/tailwindcss
```
The -D flag is the detail. This is a development dependency, not a runtime one, because the output is CSS that gets compiled into your stylesheet at build time. Nothing from this package is imported by your JavaScript, so it does not belong in your production dependencies.
Then the import, and the instruction is specific about where it goes: in the same file as your tailwindcss import.
```css
@import "tailwindcss";
/*
Choose between `mocha`, `frappe` or `macchiato` for dark mode, latte is included as the light mode flavour.
We recommend using `mocha` for dark mode.
*/
@import "@catppuccin/tailwindcss/mocha.css";
```
The order matters and the comment says why. The tailwindcss import has to come first, because Tailwind's own utilities and the theme's colour variables have to be defined before the Catppuccin stylesheet adds the utilities that reference them. The comment also records the recommendation: choose between mocha, frappe or macchiato for dark mode, latte is included as the light mode flavour, and we recommend using mocha for dark mode.
So the package expects you to pick one dark flavour for the base stylesheet, and latte is always there. The reason latte is special is the flavour-variant classes described later, because they are how you get the other three without a second import.
The style is Tailwind 4 syntax rather than Tailwind 3, and that shows in the import path. The package is imported as @catppuccin/tailwindcss/mocha.css rather than as a plugin entry in a tailwind.config.js file. There is no JavaScript config file in this package and no plugin to register, which is the difference between a Tailwind 3 plugin and a Tailwind 4 stylesheet import.
## The naming scheme, and why the ctp prefix exists
The third step shows the utilities in use, and the naming scheme is the design decision that makes the package safe to drop into an existing project:
```html
Welcome!
Hello from Latte!
```
Every colour is prefixed with ctp, so bg-ctp-base, text-ctp-text, from-ctp-red-400 and to-ctp-mauve-400. The comment says it plainly: all colours are prefixed with ctp.
That prefix is doing real work. Tailwind has its own colour scale, red-400 included, and a theme that defined unprefixed colour classes would either collide with Tailwind's built-ins or produce an unpredictable result depending on which stylesheet won. With the prefix, there is no ambiguity, and a project can use the Catppuccin palette alongside Tailwind's own colours without a second thought.
It also makes the utilities self-describing when you read the markup. bg-ctp-base tells you both the colour and that it came from this theme.
The gradient example is the more interesting one. The button uses bg-linear-50, from-ctp-red-400 and to-ctp-mauve-400, with hover:from-ctp-red and hover:to-ctp-mauve. So the palette is exposed at two levels of detail, the numbered variants like red-400 and the base ones like red, and hover states work by prefixing the same utility with the variant syntax. The bg-linear-50 utility is Tailwind 4's gradient background, and the 50 is the direction rather than a colour stop.
The gradient support is called out in its own comment, which is a small signal that it was a deliberate feature rather than an accident of how the variables were defined.
## The flavour variant classes, and how a theme switcher works
The last part of the markup example is the part that makes this more than a static palette, and it is worth separating from the rest.
Flavour variants are predefined, latte, frappe, macchiato and mocha, which allows you to force specific flavours and support custom theme switchers. And the usage is a class on a container:
```html
Hello from Latte!
```
So you put a flavour class on a wrapper element, and the colours inside it resolve to that flavour. The class name is the flavour name, latte in the example, and the paragraph inside picks up bg-ctp-base and text-ctp-text which now mean the latte values rather than whatever the stylesheet's default was.
The mechanism this enables is a theme switcher that does not reload the page and does not swap stylesheets. A button can add or remove a class on the document element, and the whole tree re-colours, because the flavour class redefines the variables and every utility is written against those variables.
That is a design that works with Tailwind 4's CSS-variable-based theming rather than against it. A plugin that hard-coded hex values into generated utilities could not do this, because the colour would be baked in at build time. A stylesheet that defines variables can, and the flavour classes are simply scoped variable redefinitions.
The trade-off is worth naming. The four flavours are fixed. You get the Catppuccin palette as Catppuccin defines it, with a limited set of named colours and a light and three dark variants, and you cannot invent a fifth flavour without forking the package. If you want the Catppuccin look with your own palette, this is the wrong tool. If you want the Catppuccin palette, and the ability to switch between its four variants at runtime, it is exactly the right one.
## The repository, and how the package is built
The repository layout shows a pnpm workspace with the package itself, a demo and a set of assets.
The top level is .editorconfig, .github/, .gitignore, LICENSE, README.md, assets/, demo/, package.json, packages/, pnpm-lock.yaml, pnpm-workspace.yaml and renovate.json. The pnpm-workspace.yaml file is what makes it a monorepo, with the packages/ directory holding the published flavours and the demo/ directory holding a working example.
The demo is a modern stack rather than a static page. It has an astro.config.mjs, so it is an Astro site, with a src/ directory, a tsconfig.json, its own package.json and a public/ directory. Astro is a sensible choice for a documentation site with a lot of live component examples, since it renders to static HTML but can still hydrate interactive parts, and the advanced examples site at tailwindcss.catppuccin.com appears to be built from it.
The root package manifest is minimal, which is what a workspace root looks like:
```json
"name": "@catppuccin/tailwindcss-monorepo",
"private": "true",
"packageManager": "pnpm@10.13.1",
"engines": {
"node": ">=22.0.0"
},
"scripts": {
"build": "pnpm -r build",
"dev": "pnpm --filter demo dev"
}
```
The name is @catppuccin/tailwindcss-monorepo and it is private, so it never reaches the registry. The packageManager field pins pnpm at 10.13.1, which with a pnpm-lock.yaml means the exact package manager version is reproducible. The engines field requires Node 22.0.0 or newer, which is a modern floor and is consistent with a Tailwind 4 project.
The two scripts are the whole build story. The build script runs pnpm -r build, which runs the build in every workspace package in dependency order, and the dev script runs pnpm --filter demo dev, which starts only the demo. So the workflow is one command for the whole workspace and one for the example site, and the filter syntax is doing the targeting so you do not have to remember which directory to change into.
There is a renovate.json at the root, so dependency updates are automated, and an .editorconfig for consistent whitespace across the tree, which matters for a repository containing generated CSS.
The maintenance section is short. The current maintainer is lemon, and there is one previous maintainer, winston. The Copyright line says 2021-present Catppuccin Org, so the palette itself predates this package by several years, and the package is one of the later ports.
## How to evaluate it, and what to check first
There are four things to consider.
First, whether you want the Catppuccin palette specifically, or a pastel theme in general. This package gives you exactly four palettes, defined by Catppuccin, with latte as the light one and frappe, macchiato and mocha as dark ones. If your brand colours are anything else, this is the wrong package.
Second, the Tailwind version, and this is the practical trap. The usage instructions use a CSS import of a .css file and utilities like bg-linear-50, which is Tailwind 4 syntax. On Tailwind 3 the pattern is a plugin registered in tailwind.config.js, and there is no such file in this package. So check your Tailwind major before you start, because the integration method is different rather than merely the class names.
Third, the naming prefix. Every colour is ctp-prefixed, which avoids a collision with Tailwind's own scale, and it also means you cannot use the colour names bare. If your existing codebase has a house convention for colour class names, this adds a second one alongside it. That is a mild cost, and the alternative, no prefix, is worse.
Fourth, whether you need runtime theme switching. The flavour classes are the feature that distinguishes this from a static colour file, and they let a switcher change the whole tree by toggling one class on a wrapper. If you only need one flavour, you could get the same colours from a hand-written CSS file with variables, and the package is then mostly about saving you the work of defining the palette.
What you get is a small, MIT licensed package with no JavaScript in it, a documented naming scheme that avoids collisions, and four palettes you can switch between at runtime. The cost is that it is a fixed palette with a fixed set of variants, and that it targets Tailwind 4's import model.
## Conclusion
Adopt @catppuccin/tailwindcss if you want the Catppuccin palette in a Tailwind 4 project, especially if you want to switch between its four flavours at runtime, since the flavour classes let a theme switcher recolour a whole subtree by toggling one class on a container. Do not adopt it if your brand palette is not Catppuccin or if you are on Tailwind 3, since the integration is a CSS import rather than a plugin and the class syntax follows Tailwind 4. Before you commit, check your Tailwind major version, install it as a development dependency rather than a runtime one, and read the existing class naming in your codebase, because the ctp prefix is a second convention alongside whatever you already use and is worth agreeing on with the team before it spreads.
## FAQ
### What is the @catppuccin/tailwindcss package?
It is a soothing pastel theme for Tailwind CSS, published on npm as @catppuccin/tailwindcss under the MIT licence. It provides the Catppuccin palette as Tailwind utilities, with every colour prefixed with ctp so the theme cannot collide with Tailwind's own colour scale.
### How do I install and import the Catppuccin Tailwind theme?
Install it as a development dependency with npm install -D @catppuccin/tailwindcss, or the pnpm or yarn equivalent. Then import it in the same file as your tailwindcss import, choosing mocha, frappe or macchiato for dark mode, with latte included as the light flavour and mocha recommended for dark mode.
### Which Catppuccin flavours are available?
Four predefined flavour variants, latte, frappe, macchiato and mocha. They can be applied as ordinary classes on a container element, which allows you to force a specific flavour and supports custom theme switchers that change the palette without a page reload.
### Does the Catppuccin Tailwind theme support gradients and hover states?
Yes. The utilities work with Tailwind 4 gradient backgrounds such as bg-linear-50 combined with from-ctp-red-400 and to-ctp-mauve-400, and hover states work by applying the standard variant prefix to the same prefixed colour utilities.
### How is the Catppuccin Tailwind package built?
As a pnpm workspace with the package itself under packages/, a demo site under demo/ built with Astro, and a root manifest that is private and pins pnpm at 10.13.1 and Node 22 or newer. The root build script runs pnpm -r build across the workspace and the dev script runs pnpm --filter demo dev for the example site.
## Sources
- [catppuccin/tailwindcss on GitHub](https://github.com/catppuccin/tailwindcss)
- [License: MIT](https://github.com/catppuccin/tailwindcss/blob/main/LICENSE)
- [Project website](https://www.npmjs.com/package/@catppuccin/tailwindcss)
- [README](https://github.com/catppuccin/tailwindcss/blob/main/README.md)
- [Releases](https://github.com/catppuccin/tailwindcss/releases)
---
Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/catppuccin-tailwindcss