# @clds/component-theme

> Define, override and use component theme

Latest version **0.56.0-beta.1** (published 2025-02-20) · 0 weekly downloads

## Install

```sh
npm install @clds/component-theme
pnpm add @clds/component-theme
yarn add @clds/component-theme
bun add @clds/component-theme
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.56.0-beta.1 |
| Published | 2025-02-20 |
| First published | 2022-06-30 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 125.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Cloudinary |
| Maintainers | cloudinary-internal |

## Links

- npm: https://www.npmjs.com/package/@clds/component-theme
- Repository: https://github.com/cloudinary/design-system
- Homepage: https://github.com/cloudinary/design-system/tree/main/libs/foundations/component-theme#readme
- Issues: https://github.com/cloudinary/design-system/issues
- npm.io page: https://npm.io/package/@clds/component-theme

## Dependencies (3)

- [es-toolkit](https://npm.io/package/es-toolkit.md) ^1.31.0
- [@clds/themes](https://npm.io/package/@clds/themes.md) 0.56.0-beta.1
- [@clds/theme-helper](https://npm.io/package/@clds/theme-helper.md) 0.56.0-beta.1

## Recent versions

- 0.56.0-beta.1 (latest) — 2025-02-20
- 0.53.5 — 2025-02-18
- 0.53.4 — 2025-02-17
- 0.53.3 — 2025-02-16
- 0.53.2 — 2025-01-30
- 0.53.1 — 2025-01-29
- 0.53.0 — 2025-01-29
- 0.52.1 — 2025-01-26
- 0.52.0 — 2025-01-20
- 0.51.5 — 2025-01-16
- 0.51.4 — 2025-01-16
- 0.51.3 — 2025-01-15
- 0.51.2 — 2025-01-15
- 0.51.1 — 2025-01-15
- 0.51.0 — 2025-01-14
- … 127 more at https://npm.io/package/@clds/component-theme/versions

## README

## @clds/component-theme

---

[![npm version](https://img.shields.io/npm/v/@clds/component-theme)](https://www.npmjs.org/package/@clds/component-theme)

This package introduces fully typed, object-oriented theming api to consume directly in your styled components.

If you consume a package which uses it, all you need is to provide correct global theme using `<ThemeProvider>` from `'styled-components'`.  
You can override such component in your application using override utility.  
You don't need any extra setup and plugins!

This api provides smart intellisense and autocompletion features for all mixins and component definition also preserving type of original theme value.

## Global theme mixins

This package exposes styled component mixins for global theme variables.

```javascript
const Button = styled.div`
  color: ${(props) => props.theme.palette.primary};
`;
```

## Component themes

The component shouldn't itself refer to global theme directly.  
Instead, it should have created a separate component theme using createTheme api.  
It introduces more semantic definitions and contain mappings to global theme.

```javascript
import { globalTheme, createTheme } from '@clds/component-theme';

export const buttonTheme = createTheme({
  border: { radius: globalTheme.spacing.lg },
  shadow: globalTheme.shadow.sm,
  text: { color: globalTheme.palette.contrastHigh },
  onState: {
    padding: globalTheme.spacing.lg,
    background: { color: globalTheme.palette.surface },
  },
  offState: {
    padding: globalTheme.spacing.sm,
    background: { color: globalTheme.palette.primary },
  },
});
```

```javascript
import buttonTheme from './myTheme';

const Button = styled.div`
  color: ${buttonTheme.palette.primary};
  background: ${buttonTheme.background.color};
`;
```

## Mixin tree

You can use mixins that were automatically created for each single global theme node, including root, all parents and leaves  
It refers to both leaves (theme values) or nodes (theme branches).  
Mixins were also created for each definition node of component theme definition.

```javascript
import { mix } from 'polished';
import { combineValues, globalTheme, propsMixin } from '@clds/component-theme';
import { buttonTheme } from './myTheme';

const Button = styled.div`
  color: ${combineValues(globalTheme.palette, propsMixin, (palette, props) => palette[props.variant])};
  background-color: ${combineValues(buttonTheme.mixValue, buttonTheme.variants, globalTheme.palette.error, propsMixin, (mixValue, buttonVariants, errorColor, props) => mix(mixValue, buttonVariants[props.variant].text.color, errorColor))};
`;
```

## Optimizations

Mixins created for parent theme nodes may cause cost calculation every render.  
They need to combine theme defaults with current overrides found in theme context.

To solve this, mixins are optimized. Every mixin tree is precompiled and cached until theme provider updates with new theme value.

## Tutorial

You can follow tutorial in storybook to see detailed usage and capabilities.

## Versioning

This library follows [Semantic Versioning](http://semver.org/).

## License

See [LICENSE](https://github.com/cloudinary/design-system/blob/main/LICENSE)

---
_Source: https://npm.io/package/@clds/component-theme · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._