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 are already set up for theming. Skip to Using theme tokens.

To set up theming in a plugin:

Install @cortexapps/plugin-core and @cortexapps/react-plugin-ui.
Import @cortexapps/react-plugin-ui/index.css in your entry file.
Call CortexApi.pluginInit() before rendering your app, so the theme arrives before your plugin renders.
Wrap your app in <PluginProvider> from @cortexapps/plugin-core/components. See the template’s App.tsx for an example.

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:

.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:

<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:

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:

.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:

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:

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:

import { Input, Label } from "@cortexapps/react-plugin-ui";

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

Cortex

Get Started

Connect data

Standardize

Improve

Streamline

Configure

Resources

Styling plugins with theme tokens

Setting up theming in your plugin

Theme token reference

Using theme tokens

Adding fallback values

Supporting light and dark mode

Using the component library

Component examples

​Setting up theming in your plugin

​Theme token reference

​Using theme tokens

​Adding fallback values

​Supporting light and dark mode

​Using the component library

​Component examples

Setting up theming in your plugin

Theme token reference

Using theme tokens

Adding fallback values

Supporting light and dark mode

Using the component library

Component examples