# @clds/theme-helper

> Helper for themes

Latest version **0.70.2** (published 2025-07-21) · 0 weekly downloads

## Install

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

## 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.70.2 |
| Published | 2025-07-21 |
| First published | 2022-06-10 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 83.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Cloudinary |
| Maintainers | cloudinary-internal |

## Links

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

## Dependencies (2)

- [es-toolkit](https://npm.io/package/es-toolkit.md) 1.31.0
- [@clds/themes](https://npm.io/package/@clds/themes.md) 0.70.2

## Recent versions

- 0.70.2 (latest) — 2025-07-21
- 0.70.1 — 2025-07-08
- 0.70.0 — 2025-07-06
- 0.69.0 — 2025-06-26
- 0.68.0 — 2025-06-24
- 0.67.1 — 2025-06-12
- 0.67.0 — 2025-06-12
- 0.66.0 — 2025-06-09
- 0.65.0 — 2025-06-08
- 0.64.2 — 2025-06-05
- 0.64.1 — 2025-06-03
- 0.64.0 — 2025-06-03
- 0.63.1 — 2025-05-25
- 0.63.0 — 2025-05-06
- 0.62.4 — 2025-04-09
- … 157 more at https://npm.io/package/@clds/theme-helper/versions

## README

## @clds/theme-helper

---

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

This package was created to simplify the usage of themes when working with [styled-components](https://github.com/styled-components/styled-components). It provides a default theme (that all applications themes should merge with),  
a theme API so components will be able to access the theme values easily and some utility functions to work with themes

## Installation

Install the package using Package Manager:

```sh
yarn add @clds/theme-helper
pnpm add @clds/theme-helper
npm install --save @clds/theme-helper
```

## switchProp

In case your component receive a prop and you want to get different theme variable based on the prop value you can use this function

### API:

## generateTheme

When using the the `ThemeProvider` from [styled-components](https://github.com/styled-components/styled-components) you should provide a theme object,  
In order to support some extra features like base theme, references to other theme variables (from application or default theme) and more we created this function.

You should invoke it with your theme and send the result to the `ThemeProvider`

```javascript
import { ThemeProvider } from 'styled-components';
import { generateTheme } from '@clds/theme-helper';
import { theme } from './myTheme';

const App = (props) => (
  <ThemeProvider theme={generateTheme(theme)}>
    <MyButton high={true}>Button</MyButton>
  </ThemeProvider>
);
```

## Default theme

this package also contains a default theme,  
this is the base theme and every application can override it by providing it's own theme with overrides,

When adding or updating a component that should be affected from the theme variables there are few steps that should be done

### 1. add the relevant variables to the default theme

We should add variables for each component and not use existing global variables,  
this will give the applications much more flexibility when creating their own themes.  
We should use references to other theme variables so we won't need to duplicate values.  
**The default theme filename is `default.theme.js`**.

#### Example:

```javascript
//default.theme.js

const myComponent = {
  color: 'colors.primary',
};

module.exports = {
  ...myComponent,
};
```

This will take our component color from the primary color that's under the colors section in the theme.

### 2. add the mappings to the variables that we added to the theme

In order to provide the `themeApi` we have a mappings file,  
when updating the default theme we should also update the mappings file so the themeApi will expose our variables and point to the correct locations in the theme
**The mappings filename is `mappings.js`**.

#### Example:

```javascript
//mappings.js

export default {
  ...,
  myComponentColor: 'myComponent.color',
}
```

Now you will be able to use `theme.myComponentColor` in your component and let the applications customize it when providing their theme

## 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/theme-helper · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._