# Canvas Kit Theming
> **Deprecation Notice:** The `theme` prop on `CanvasProvider` and all associated theming utilities
> (`useTheme`, `getTheme`, `styled`, `defaultCanvasTheme`, `ContentDirection`, etc.) are deprecated.
> Please use CSS variables from `@workday/canvas-tokens-web` for theming. For the full theming
> guide, see our
> [Theming Documentation](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs).
## Sana Canvas Theme
For application-level theming in v16, import the Sana CSS variables and set `data-theme="sana-canvas"`
on ``. See the
[v16 Upgrade Guide](https://workday.github.io/canvas-kit/?path=/docs/guides-upgrade-guides-v-16-0-overview--docs#sana-canvas-theme)
for the canonical setup. The `CanvasProvider` `theme` prop is for **scoped** theming only.
## Installation
```sh
yarn add @workday/canvas-kit-react/common
```
## Recommended Approach: CSS Variables
Canvas Kit v16 promotes using CSS variables for theming. Import CSS variable files and override
values in your root CSS:
```css
/* index.css */
@import '@workday/canvas-tokens-web/css/base/_variables.css';
@import '@workday/canvas-tokens-web/css/system/_variables.css';
@import '@workday/canvas-tokens-web/css/brand/_variables.css';
@import '@workday/canvas-tokens-web/css/component/_variables.css';
@import '@workday/canvas-tokens-web/css/sana/_variables.css';
:root {
/* Override brand primary colors */
--cnvs-brand-primary-600: var(--cnvs-base-palette-magenta-600);
--cnvs-brand-primary-500: var(--cnvs-base-palette-magenta-500);
--cnvs-brand-primary-A50: var(--cnvs-base-palette-magenta-A50);
}
```
Or use `createStyles` to generate themed class names:
```tsx
import {CanvasProvider} from '@workday/canvas-kit-react/common';
import {createStyles} from '@workday/canvas-kit-styling';
import {base, brand} from '@workday/canvas-tokens-web';
const themedBrand = createStyles({
[brand.primary600]: base.magenta600,
[brand.primary700]: base.magenta700,
});
;
```
## Scoped Theming (CanvasProvider)
For embedded or multi-brand sections, use the numerical `brand` shape:
```tsx
import {CanvasProvider} from '@workday/canvas-kit-react/common';
import {base} from '@workday/canvas-tokens-web';
```
### Popups and `sanaCanvasProviderTheme`
Popups (menus, selects, modals) portal to `document.body`. Theme inheritance depends on where
`data-theme="sana-canvas"` lives:
- **You control ``:** set `data-theme="sana-canvas"` there. Popups inherit Sana variables —
no `theme` prop needed.
- **You cannot control ``** (embedded apps, microfrontends, third-party shells): pass
`sanaCanvasProviderTheme` to your root `CanvasProvider`. Nested `data-theme` on a wrapper does
not reach portaled popups; this preset forwards Sana brand variables onto the popup stack.
```tsx
import {CanvasProvider, sanaCanvasProviderTheme} from '@workday/canvas-kit-react/common';
// Required when is unavailable
```
See the [Theming documentation](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs) for details.
## Bidirectionality (RTL Support)
### Setting RTL Direction
Use the native HTML `dir` attribute to set the text direction. The `CanvasProvider` accepts a `dir`
prop:
```tsx
import {CanvasProvider} from '@workday/canvas-kit-react/common';
;
```
### CSS Logical Properties
Use
[CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties)
for styling. These automatically adapt to the text direction:
```css
/* Use CSS logical properties */
.my-component {
margin-inline-start: 1rem; /* Instead of margin-left */
padding-inline-end: 1rem; /* Instead of padding-right */
}
```
### Conditional RTL Styles
For styles that need to change based on direction, use the
[`:dir()` pseudo-class selector](https://developer.mozilla.org/en-US/docs/Web/CSS/:dir):
```css
/* Use :dir() for RTL-specific styles */
.my-component:dir(rtl) {
/* RTL-specific styles */
}
```
```tsx
import {createStyles} from '@workday/canvas-kit-styling';
const styles = createStyles({
':dir(rtl)': {
svg: {
transform: 'rotate(180deg)',
},
},
});
```
## Breakpoints
Breakpoints are used by media queries to conditionally apply or modify styles based on viewport
width.
### Values
| Name | Size (px) |
| ------ | --------- |
| `zero` | 0 |
| `s` | 320 |
| `m` | 768 |
| `l` | 1024 |
| `xl` | 1440 |
Standard screen size ranges:
- `small` (320px - 767px) - Mobile screens
- `medium` (768px - 1023px) - Tablet screens
- `large` (1024px - 1439px) - Laptop/small desktop screens
- `extra-large` (≥1440px) - Large screens
### Using Breakpoints
You can use standard CSS media queries:
```css
@media (min-width: 768px) {
.my-component {
padding: 1rem;
}
}
```
---
## Deprecated API Reference
The following APIs are deprecated and should not be used in new code.
### ~~CanvasProvider theme prop~~ (Deprecated)
```tsx
// DEPRECATED - Do not use
```
### ~~useTheme / getTheme~~ (Deprecated)
```tsx
// DEPRECATED - Use CSS variables instead
const theme = useTheme();
const theme = getTheme();
```
### ~~styled~~ (Deprecated)
```tsx
// DEPRECATED - Use createStyles or createStencil instead
import {styled} from '@workday/canvas-kit-react/common';
```
### ~~ContentDirection~~ (Deprecated)
```tsx
// DEPRECATED - Use :dir() pseudo-class and CSS logical properties instead
import {ContentDirection} from '@workday/canvas-kit-react/common';
```
### ~~defaultCanvasTheme~~ (Deprecated)
```tsx
// DEPRECATED - Use defaultBranding instead
import {defaultCanvasTheme} from '@workday/canvas-kit-react/common';
// NEW - Use defaultBranding
import {defaultBranding} from '@workday/canvas-kit-react/common';
```
For detailed migration guidance, see our
[Theming Documentation](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs).