---
title: "Tailwind CSS Integration"
slug: ovhcloud-design-system-customize-tailwind-css-integration
category: generic
type: overview
version: 20.0.0
tokens: 2634
source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-customize-tailwind-css-integration.txt
---
# Tailwind CSS Integration
This guide covers how to use Tailwind CSS utilities with the OVHcloud Design System (ODS) design tokens.
Tailwind CSS is not mandatory: ODS is not based on it, and `@ovhcloud/ods-react` does not depend on it. `@ovhcloud/ods-tailwind` is an opt-in package for the apps that use Tailwind CSS v4: it maps the Tailwind utilities to the ODS semantic tokens, so that `bg-ods-surface-raised` or `rounded-ods-container` read the same values as the ODS components.
## Installation
`@ovhcloud/ods-tailwind` requires Tailwind CSS v4.
```bash
npm install @ovhcloud/ods-tailwind tailwindcss @tailwindcss/vite
```
Add the Tailwind plugin of your bundler, for instance with Vite:
```typescript
// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [react(), tailwindcss()],
});
```
Then import `@ovhcloud/ods-tailwind` in your stylesheet, followed by the ODS theme. It brings Tailwind CSS itself: do not import `tailwindcss` again.
```css
/* index.css */
@import '@ovhcloud/ods-tailwind';
@import '@ovhcloud/ods-themes/default/css';
@import '@ovhcloud/ods-themes/default/fonts';
```
### Import order
Import this stylesheet **before any ODS theme or component**, as the first import of your entry point, and import the ODS theme from it rather than from JavaScript:
```typescript
// main.tsx
import './index.css';
import { createRoot } from 'react-dom/client';
import { App } from './App';
```
> `@ovhcloud/ods-tailwind` declares the order of the CSS layers: the Tailwind theme and base, then the ODS layers, then the Tailwind components and utilities. A layer takes its place from the first stylesheet that names it, and the ODS theme and components name the ODS layers too. If either is imported before `@ovhcloud/ods-tailwind`, the ODS layers land before the Tailwind base styles, which then reset the ODS buttons and headings.
With this order, the ODS styles win over the Tailwind base styles, and your own styles win over the ODS ones: a utility on an ODS component, or a rule of yours in `@layer components`, where Tailwind puts the styles of your components. Target an ODS element with a class rather than a tag selector there: a `.card button` rule in `@layer components` also restyles every ODS button of the card.
For an order that holds whatever the import order, declare it in the `
` of your page, before any stylesheet:
```html
```
With a Content Security Policy, allow this inline style with its hash or a nonce.
## Utilities
Every utility has an `ods-` prefix, which keeps it apart from the Tailwind defaults (these stay available):
ODS tokens
Utilities
--ods-semantic-color-*
bg-ods-surface-raised, text-ods-content-heading, border-ods-border-container, and every other color utility (fill-, ring-, outline-…)
A utility is named after its token: `--ods-semantic-color-surface-raised` gives `bg-ods-surface-raised`, `--ods-semantic-size-space-gap-group` gives `gap-ods-gap-group`. See [Design Tokens](https://ovh.github.io/design-system/v20.0.0/guides/design-tokens) for what each token is for. The palette (`--ods-palette-*`) is not mapped: use the semantic tokens, the ones a theme re-points.
```tsx
import { BADGE_STATUS, Badge, TEXT_PRESET, Text } from '@ovhcloud/ods-react';
function Summary() {
return (
Your orderReady
);
}
```
On a solid ground, use the content token made for it: `bg-ods-surface-brand` goes with `text-ods-content-on-brand-solid`. `bg-ods-brand` is the brand color of the logo, not a surface.
The page font is the ODS body font, and the monospace font the ODS code font: the Tailwind base styles set them on the page, so the ODS components and their overlays (Modal, Popover, Tooltip…) inherit them with no class.
The tokens Tailwind has no theme for are not mapped. Read them with the variable shorthand: `z-(--ods-semantic-z-index-modal)`, `opacity-(--ods-semantic-opacity-disabled)`, `duration-(--ods-semantic-motion-duration-fast)`.
## Themes
The utilities read the ODS tokens (`var(--ods-semantic-…)`), never their values. The same classes follow the theme the page loads, dark themes included, with no Tailwind configuration: load another theme, or switch themes as [Themes](https://ovh.github.io/design-system/v20.0.0/guides/themes) explains, and they change with it.
Import another theme instead of the default one, after `@ovhcloud/ods-tailwind`. A theme is complete: import only one, with the fonts it names.
```css
/* index.css, with the Blue Jeans dark theme */
@import '@ovhcloud/ods-tailwind';
@import '@ovhcloud/ods-themes/blue-jeans-dark/css';
@import '@ovhcloud/ods-themes/default/fonts';
```
To follow the system setting with no JavaScript, condition each mode on it, so that only one applies:
```css
@import '@ovhcloud/ods-tailwind';
@import '@ovhcloud/ods-themes/default/css' (prefers-color-scheme: light);
@import '@ovhcloud/ods-themes/aluminium-dark/css' (prefers-color-scheme: dark);
@import '@ovhcloud/ods-themes/default/fonts';
```
A theme switched from your code, as [Themes](https://ovh.github.io/design-system/v20.0.0/guides/themes) does it with a `` in the ``, is loaded outside `@ovhcloud/ods-tailwind`: declare the layer order first in the ``, before that `` (see **Import order**), or the theme sets it and the Tailwind base styles reset the ODS components.
```html
```
### The dark variant
If your own classes use the `dark:` variant, make it follow the same switch as the ODS dark theme. By default, it follows the color scheme of the operating system, as a dark theme loaded with `(prefers-color-scheme: dark)` does. If your code swaps the light and dark themes, also set an attribute of your own on ``, `data-dark` for instance, and point the variant at it:
```css
/* Tailwind CSS v4, in index.css */
@custom-variant dark (&:where([data-dark], [data-dark] *));
```
```js
// Tailwind CSS v3, in tailwind.config.js
export default {
darkMode: ['selector', '[data-dark]'],
// …
};
```
ODS itself reads no attribute: `data-dark` only drives your `dark:` classes.
### Without the layer order
If your app already sets its own Tailwind entry point and layer order, import only the utilities, after Tailwind, and after any reset of a namespace (`--color-*: initial`), which would clear the ODS utilities too:
```css
@import 'tailwindcss';
@import '@ovhcloud/ods-tailwind/theme.css';
```
Then keep the ODS layers (`ods-quarks`, `ods-atoms`, `ods-molecules`, `ods-organisms`) after the Tailwind `base` layer and before `components` in your own `@layer` statement.
## Tailwind CSS v3
`@ovhcloud/ods-tailwind` requires Tailwind CSS v4. With Tailwind CSS v3, map the tokens you need in your `tailwind.config.js`, under the same names:
```js
/** @type {import('tailwindcss').Config} */
export default {
content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
theme: {
extend: {
borderRadius: {
'ods-container': 'var(--ods-semantic-size-radius-container)',
'ods-control': 'var(--ods-semantic-size-radius-control)',
},
colors: {
'ods-border-container': 'var(--ods-semantic-color-border-container)',
'ods-content-heading': 'var(--ods-semantic-color-content-heading)',
'ods-surface-raised': 'var(--ods-semantic-color-surface-raised)',
},
fontFamily: {
'ods-body': 'var(--ods-semantic-font-family-body)',
},
},
},
};
```
Tailwind CSS v3 has no layer order of its own to declare: its base styles do not use cascade layers, so they always win over the ODS styles and reset the ODS buttons and headings. Leave the Tailwind preflight out: `corePlugins: { preflight: false }`.
## Integration with IDEs
In VS Code, install the [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) extension: the `ods-*` classes complete from your CSS file (v4) or your configuration (v3). In Tailwind CSS v4, if the extension does not find your CSS file, point its `tailwindCSS.experimental.configFile` setting at it. JetBrains IDEs complete them with no setup.
## Resources
- [Tailwind CSS theme variables](https://tailwindcss.com/docs/theme)
- [Tailwind CSS v4 upgrade guide](https://tailwindcss.com/docs/upgrade-guide)
- [ODS Themes](https://ovh.github.io/design-system/v20.0.0/guides/themes)
- [ODS Design Tokens](https://ovh.github.io/design-system/v20.0.0/guides/design-tokens)