# @wordpress/global-styles-engine

> Pure CSS generation engine for WordPress global styles.

Latest version **1.22.0** (published 2026-09-10) · GPL-2.0-or-later license · 0 weekly downloads

## Install

```sh
npm install @wordpress/global-styles-engine
pnpm add @wordpress/global-styles-engine
yarn add @wordpress/global-styles-engine
bun add @wordpress/global-styles-engine
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; popular repo.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.22.0 |
| Published | 2026-09-10 |
| First published | 2025-10-22 |
| Weekly downloads | 0 |
| License | GPL-2.0-or-later |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.12.0 |
| Dependencies | 10 |
| Unpacked size | 1.1 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 11754 |
| Author | The WordPress Contributors |
| Maintainers | garypendergast, adamsilverstein, gziolo, ntwb, riad, noisysocks, kadamwhite, gutenbergplugin, jorgefilipecosta, ellatrix, iandunn206, whyisjake, ockham, sirreal, nosolosw, wpisabel, ntsekouras, nerrad, desrosj, talldanwp, peterwilsoncc, ryanwelcher, mamaduka, aduth, johnbillion |
| Keywords | wordpress, gutenberg, global styles |

## Links

- npm: https://www.npmjs.com/package/@wordpress/global-styles-engine
- Repository: https://github.com/WordPress/gutenberg
- Homepage: https://github.com/WordPress/gutenberg/tree/HEAD/packages/patterns/README.md
- Issues: https://github.com/WordPress/gutenberg/issues
- npm.io page: https://npm.io/package/@wordpress/global-styles-engine

## Dependencies (10)

- [colord](https://npm.io/package/colord.md) ^2.9.3
- [memize](https://npm.io/package/memize.md) ^2.1.1
- [deepmerge](https://npm.io/package/deepmerge.md) ^4.3.1
- [@wordpress/data](https://npm.io/package/@wordpress/data.md) ^10.55.0
- [@wordpress/i18n](https://npm.io/package/@wordpress/i18n.md) ^6.28.0
- [fast-deep-equal](https://npm.io/package/fast-deep-equal.md) ^3.1.3
- [is-plain-object](https://npm.io/package/is-plain-object.md) ^5.1.0
- [@wordpress/blocks](https://npm.io/package/@wordpress/blocks.md) ^16.0.0
- [@wordpress/private-apis](https://npm.io/package/@wordpress/private-apis.md) ^1.55.0
- [@wordpress/style-engine](https://npm.io/package/@wordpress/style-engine.md) ^2.55.0

## Recent versions

- 1.22.0 (latest) — 2026-09-10
- 1.21.2-next.v.202609031004.0 (next) — 2026-09-03
- 1.7.1 (wp-7.0) — 2026-06-30
- 1.21.1-next.v.202608281122.0 — 2026-08-28
- 1.21.0 — 2026-08-26
- 1.20.0 — 2026-08-12
- 1.19.0 — 2026-07-29
- 1.18.0 — 2026-07-14
- 1.17.1-next.v.202607070741.0 — 2026-07-07
- 1.17.0 — 2026-07-01
- 1.16.0 — 2026-06-24
- 1.15.2-next.v.202606191442.0 — 2026-06-19
- 1.15.1 — 2026-06-16
- 1.14.1 — 2026-06-04
- 1.15.0 — 2026-06-04
- … 42 more at https://npm.io/package/@wordpress/global-styles-engine/versions

## README

# Global Styles Engine

A generic library for reading and writing global styles data structures (theme.json format).

## Overview

This is a framework-agnostic utility library that provides functions for manipulating global styles objects. It handles the complex nested structure of theme.json format, including block-specific styles and settings.

## API

### Reading Data

#### `getStyle(globalStyles, path, blockName?, shouldDecodeEncode?)`

Get a style value from the global styles object.

```typescript
// Get global text color
const textColor = getStyle( globalStyles, 'color.text' );

// Get button background color
const buttonBg = getStyle( globalStyles, 'color.background', 'core/button' );

// Get raw value without CSS variable resolution
const rawValue = getStyle( globalStyles, 'color.text', undefined, false );
```

#### `getSetting(globalStyles, path, blockName?)`

Get a setting value with fallback hierarchy (block-specific → global).

```typescript
// Get global color palette
const colors = getSetting( globalStyles, 'color.palette' );

// Get paragraph-specific font sizes
const fontSizes = getSetting(
	globalStyles,
	'typography.fontSizes',
	'core/paragraph'
);
```

### Writing Data

#### `setStyle(globalStyles, path, newValue, blockName?)`

Immutably set a style value. Returns a new global styles object.

```typescript
// Set global text color
const updated = setStyle( globalStyles, 'color.text', '#333333' );

// Set button background color
const updated = setStyle(
	globalStyles,
	'color.background',
	'#0073aa',
	'core/button'
);
```

#### `setSetting(globalStyles, path, newValue, blockName?)`

Immutably set a setting value. Returns a new global styles object.

```typescript
// Set global color palette
const updated = setSetting( globalStyles, 'color.palette', newPalette );

// Set block-specific settings
const updated = setSetting(
	globalStyles,
	'typography.fontSizes',
	sizes,
	'core/heading'
);
```

### Utility Functions

#### `getPalettes(globalStyles)`

Extract color palettes organized by origin (theme, custom, default).

#### `generateGlobalStyles(globalStyles)`

Generate CSS from global styles object.

#### `mergeGlobalStyles(base, user)`

Merge multiple global styles objects with proper precedence.

## Data Structure

The global styles object follows the theme.json schema:

```typescript
{
  styles: {
    color: { text: '#000', background: '#fff' },
    typography: { fontSize: '16px' },
    elements: {
      button: { color: { background: 'blue' } }
    },
    blocks: {
      'core/paragraph': { color: { text: '#333' } }
    }
  },
  settings: {
    color: { palette: [...] },
    typography: { fontSizes: [...] },
    blocks: {
      'core/paragraph': { color: { text: true } }
    }
  }
}
```

## Features

-   **Immutable Updates**: All setter functions return new objects
-   **Type Safety**: Full TypeScript support
-   **CSS Variable Resolution**: Automatic resolution of CSS custom properties
-   **Block-Specific Styles**: Support for block and element-specific styling
-   **Fallback Hierarchy**: Smart fallback from block → global → default settings
-   **Framework Agnostic**: No dependencies on React, WordPress, or other frameworks

## Usage

This library is designed to be used as the foundation for any global styles editing interface. It provides the core data manipulation functions while remaining completely generic and reusable.

It is a prerequisite for use that blocks and their styles be globally registered, because block styles are fetched from the global blocks store.

---
_Source: https://npm.io/package/@wordpress/global-styles-engine · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._