> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cortex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Styling plugins with theme tokens

This article covers styling your plugin with theme tokens, the CSS variables Cortex passes to plugins so they match the look and feel of the rest of the product. Tokens reflect the current user's theme, including custom brand colors and light or dark mode.

## Setting up theming in your plugin

> Plugins created from the [plugin template](https://github.com/cortexapps/cookiecutter-cortex-plugin) are already set up for theming. Skip to [Using theme tokens](#using-theme-tokens).

To set up theming in a plugin:

1. Install `@cortexapps/plugin-core` and `@cortexapps/react-plugin-ui`.
2. Import `@cortexapps/react-plugin-ui/index.css` in your entry file.
3. Call `CortexApi.pluginInit()` before rendering your app, so the theme arrives before your plugin renders.
4. Wrap your app in `<PluginProvider>` from `@cortexapps/plugin-core/components`. See the template's [App.tsx](https://github.com/cortexapps/cookiecutter-cortex-plugin/blob/master/%7B%7Bcookiecutter.project_name%7D%7D/src/components/App.tsx) for an example.

```tsx theme={null}
import { createRoot } from "react-dom/client";
import { CortexApi } from "@cortexapps/plugin-core";
import "@cortexapps/react-plugin-ui/index.css";
import App from "./components/App";

document.addEventListener("DOMContentLoaded", () => {
  // request the theme from Cortex and subscribe to theme changes
  CortexApi.pluginInit();

  createRoot(document.getElementById("cortex-plugin-root")!).render(<App />);
});
```

If the tokens aren't applied, make sure `@cortexapps/plugin-core` is up to date, `CortexApi.pluginInit()` is called before your app renders and your app is wrapped in `<PluginProvider>`.

## Theme token reference

The following tokens are available to your plugin.

| Token | Use |
| :- | :- |
| `--cortex-plugin-background` | Page background |
| `--cortex-plugin-foreground` | Default text |
| `--cortex-plugin-primary` | Primary actions and highlights |
| `--cortex-plugin-secondary` | Secondary buttons and surfaces |
| `--cortex-plugin-muted` | Subdued backgrounds and secondary text |
| `--cortex-plugin-accent` | Hover and highlight states |
| `--cortex-plugin-accent-foreground` | Text on accent backgrounds |
| `--cortex-plugin-destructive` | Error backgrounds |
| `--cortex-plugin-destructive-foreground` | Text on error backgrounds |
| `--cortex-plugin-border` | Borders and dividers |
| `--cortex-plugin-input` | Input fields |
| `--cortex-plugin-ring` | Focus rings |

## Using theme tokens

Reference a token anywhere you would use a color value. For example, in CSS:

```css theme={null}
.panel {
  background-color: var(--cortex-plugin-background);
  color: var(--cortex-plugin-foreground);
  border: 1px solid var(--cortex-plugin-border);
}
```

If you use Tailwind, reference tokens with arbitrary values:

```tsx theme={null}
<div className="bg-[var(--cortex-plugin-muted)] border-[var(--cortex-plugin-border)]" />
```

### Adding fallback values

Add a fallback value so your plugin still renders correctly if the theme hasn't loaded yet:

```css theme={null}
background-color: var(--cortex-plugin-background, #fff);
```

> **Note:** Fallbacks are fixed values, so they don't follow brand colors or dark mode.

## Supporting light and dark mode

You don't need to define separate colors for light and dark mode. Token values change with the user's setting, so anything styled with tokens switches automatically.

`<PluginProvider>` also adds a `light` or `dark` class to the `<html>` element. Use this class for anything the tokens don't cover, such as swapping an image:

```css theme={null}
.dark .logo {
  content: url("logo-dark.svg");
}
```

## Using the component library

The quickest way to match Cortex is to build your plugin with `@cortexapps/react-plugin-ui`. Its components already use the theme tokens, so they follow the user's theme with no extra styling.

The library includes the following components:

* Badge
* Breadcrumb
* Button
* Card
* Checkbox
* Dialog
* Input
* Label
* Loader
* Progress
* Select
* Tabs
* Typeahead

### Component examples

Import components from `@cortexapps/react-plugin-ui`. For example, a card with a badge and a button:

```tsx theme={null}
import { Badge, Button, Card, CardContent, CardHeader, CardTitle } from "@cortexapps/react-plugin-ui";

<Card>
  <CardHeader>
    <CardTitle>payments-service</CardTitle>
  </CardHeader>
  <CardContent>
    <Badge variant="success">Passing</Badge>
    <Button variant="outline">View details</Button>
  </CardContent>
</Card>
```

Tabs:

```tsx theme={null}
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@cortexapps/react-plugin-ui";

<Tabs defaultValue="overview">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="settings">Settings</TabsTrigger>
  </TabsList>
  <TabsContent value="overview">...</TabsContent>
  <TabsContent value="settings">...</TabsContent>
</Tabs>
```

An input with a label:

```tsx theme={null}
import { Input, Label } from "@cortexapps/react-plugin-ui";

<Label htmlFor="service-name">Service name</Label>
<Input id="service-name" placeholder="Enter a service name" />
```


## Related topics

- [Editing a plugin](/streamline/plugins/creating-plugins/editing-a-plugin.md)
- [Creating a plugin](/streamline/plugins/creating-plugins.md)
- [Visualizing custom data in a plugin](/guides/operational-readiness/visualizing-custom-data-in-a-plugin.md)