# StylesMap

class

Styles map. Allows handling (adding, removing, retrieving) a set of style rules (usually, of an element).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L18)

<a id="properties">

## Properties

<a id="member-isEmpty">

### `isEmpty: boolean` _(readonly)_

Returns true if style map has no styles set.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L53)

<a id="member-size">

### `size: number` _(readonly)_

Number of styles defined.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L62)

<a id="member-_cachedExpandedStyleNames">

### `_cachedExpandedStyleNames: Array<string> | null` _(private)_

Cached list of expanded style names for faster access.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L35)

<a id="member-_cachedStyleNames">

### `_cachedStyleNames: Array<string> | null` _(private)_

Cached list of style names for faster access.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L30)

<a id="member-_styleProcessor">

### `_styleProcessor: StylesProcessor` _(private)_

An instance of the [`StylesProcessor`](module_engine_view_stylesmap-StylesProcessor.md).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L40)

<a id="member-_styles">

### `_styles: Styles` _(private)_

Keeps an internal representation of styles map. Normalized styles are kept as object tree to allow unified modification and value access model using lodash's get, set, unset, etc methods.

When no style processor rules are defined it acts as simple key-value storage.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L25)

<a id="methods">

## Methods

<a id="function-constructor">

### `constructor( styleProcessor )`

Creates Styles instance.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L45)

#### Parameters

* `styleProcessor: StylesProcessor`

<a id="function-clear">

### `clear() → void`

Removes all styles.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L466)

#### Returns

* `void`

<a id="function-getAsString">

### `getAsString( propertyName ) → string | undefined`

Returns property as a value string or undefined if property is not set.

```typescript
// Enable 'margin' shorthand processing:
editor.data.addStyleProcessorRules( addMarginStylesRules );

const styles = new Styles();
styles.setTo( 'margin:1px;' );
styles.set( 'margin-bottom', '3em' );

styles.getAsString( 'margin' ); // -> 'margin: 1px 1px 3em;'
```

Note, however, that all sub-values must be set for the longhand property name to return a value:

```typescript
const styles = new Styles();
styles.setTo( 'margin:1px;' );
styles.remove( 'margin-bottom' );

styles.getAsString( 'margin' ); // -> undefined
```

In the above scenario, it is not possible to return a `margin` value, so `undefined` is returned. Instead, you should use:

```typescript
const styles = new Styles();
styles.setTo( 'margin:1px;' );
styles.remove( 'margin-bottom' );

for ( const styleName of styles.getStyleNames() ) {
	console.log( styleName, styles.getAsString( styleName ) );
}
// 'margin-top', '1px'
// 'margin-right', '1px'
// 'margin-left', '1px'
```

In general, it is recommend to iterate over style names like in the example above. This way, you will always get all the currently set style values. So, if all the 4 margin values would be set the for-of loop above would yield only `'margin'`, `'1px'`:

```typescript
const styles = new Styles();
styles.setTo( 'margin:1px;' );

for ( const styleName of styles.getStyleNames() ) {
	console.log( styleName, styles.getAsString( styleName ) );
}
// 'margin', '1px'
```

**Note**: To get a normalized version of a longhand property use the [`#getNormalized()`](#function-getNormalized) method.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L403)

#### Parameters

* `propertyName: string`

#### Returns

* `string | undefined`

<a id="function-getNormalized">

### `getNormalized( name? ) → StyleValue | undefined`

Returns a normalized style object or a single value.

```typescript
// Enable 'margin' shorthand processing:
editor.data.addStyleProcessorRules( addMarginStylesRules );

const styles = new Styles();
styles.setTo( 'margin:1px 2px 3em;' );

styles.getNormalized( 'margin' );
// will log:
// {
//	 top: '1px',
//	 right: '2px',
//	 bottom: '3em',
//	 left: '2px'	 // normalized value from margin shorthand
// }

styles.getNormalized( 'margin-left' ); // -> '2px'
```

**Note**: This method will only return normalized styles if a style processor was defined.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L308)

#### Parameters

* `name?: string`

  Style name.

#### Returns

* `StyleValue | undefined`

<a id="function-getStyleNames">

### `getStyleNames( expand ) → Array<string>`

Returns all style properties names as they would appear when using [`#toString()`](#function-toString).

When `expand` is set to true and there's a shorthand style property set, it will also return all equivalent styles:

```typescript
stylesMap.setTo( 'margin: 1em' )
```

will be expanded to:

```typescript
[ 'margin', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left' ]
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L440)

#### Parameters

* `expand: boolean`

  Expand shorthand style properties and all return equivalent style representations.

  Defaults to `false`

#### Returns

* `Array<string>`

<a id="function-getStylesEntries">

### `getStylesEntries() → Array<StylePropertyDescriptor>`

Returns normalized styles entries for further processing.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L492)

#### Returns

* `Array<StylePropertyDescriptor>`

<a id="function-has">

### `has( name ) → boolean`

Checks if a given style is set.

```typescript
styles.setTo( 'margin-left:1px;' );

styles.has( 'margin-left' );	// -> true
styles.has( 'padding' );		// -> false
```

**Note**: This check supports normalized style names.

```typescript
// Enable 'margin' shorthand processing:
editor.data.addStyleProcessorRules( addMarginStylesRules );

styles.setTo( 'margin:2px;' );

styles.has( 'margin' );		 // -> true
styles.has( 'margin-top' );	 // -> true
styles.has( 'margin-left' );	// -> true

styles.remove( 'margin-top' );

styles.has( 'margin' );		 // -> false
styles.has( 'margin-top' );	 // -> false
styles.has( 'margin-left' );	// -> true
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L120)

#### Parameters

* `name: string`

  Style name.

#### Returns

* `boolean`

<a id="function-isSimilar">

### `isSimilar( other ) → boolean`

Returns `true` if both attributes have the same styles.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L475)

#### Parameters

* `other: StylesMap`

#### Returns

* `boolean`

<a id="function-keys">

### `keys() → Array<string>`

Alias for [`getStyleNames`](#function-getStyleNames).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L459)

#### Returns

* `Array<string>`

<a id="function-remove">

### `remove( names ) → void`

Removes given style.

```typescript
styles.setTo( 'background:#f00;margin-right:2px;' );

styles.remove( 'background' );

styles.toString();   // -> 'margin-right:2px;'
```

_**Note**:_ This method uses [enabled style processor rules](module_engine_controller_datacontroller-DataController.md#function-addStyleProcessorRules) to normalize passed values.

```typescript
// Enable 'margin' shorthand processing:
editor.data.addStyleProcessorRules( addMarginStylesRules );

styles.setTo( 'margin:1px' );

styles.remove( 'margin-top' );
styles.remove( 'margin-right' );

styles.toString(); // -> 'margin-bottom:1px;margin-left:1px;'
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L254)

#### Parameters

* `names: ArrayOrItem<string>`

  Style name or an array of names.

#### Returns

* `void`

<a id="function-set:CONFIG_OBJECT">

### `set( styles ) → void`

Sets many styles at once:

```typescript
styles.set( {
	color: 'blue',
	'margin-right': '1em'
} );
```

It is equivalent to:

```typescript
styles.set( 'color', 'blue' );
styles.set( 'margin-right', '1em' );
```

See [`set`](#function-set:KEY_VALUE)

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L211)

#### Parameters

* `styles: Styles`

#### Returns

* `void`

<a id="function-set:KEY_VALUE">

### `set( name, value ) → void`

Sets a given style.

Can insert one by one:

```typescript
styles.set( 'color', 'blue' );
styles.set( 'margin-right', '1em' );
```

_**Note**:_ This method uses [enabled style processor rules](module_engine_controller_datacontroller-DataController.md#function-addStyleProcessorRules) to normalize passed values.

```typescript
// Enable 'margin' shorthand processing:
editor.data.addStyleProcessorRules( addMarginStylesRules );

styles.set( 'margin', '2px' );
```

The above code will set margin to:

```typescript
styles.getNormalized( 'margin' );
// -> { top: '2px', right: '2px', bottom: '2px', left: '2px' }
```

Which makes it possible to retrieve a "sub-value":

```typescript
styles.get( 'margin-left' );	   // -> '2px'
```

Or modify it:

```typescript
styles.remove( 'margin-left' );

styles.getNormalized( 'margin' );  // -> { top: '1px', bottom: '1px', right: '1px' }
styles.toString();				 // -> 'margin-bottom:1px;margin-right:1px;margin-top:1px;'
```

This method also allows to set normalized values directly (if a particular styles processor rule was enabled):

```typescript
styles.set( 'border-color', { top: 'blue' } );
styles.set( 'margin', { right: '2em' } );

styles.toString();				 // -> 'border-color-top:blue;margin-right:2em;'
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L188)

#### Parameters

* `name: string`

  Style property name.

* `value: StyleValue`

  Value to set.

#### Returns

* `void`

<a id="function-setTo">

### `setTo( inlineStyle ) → this`

Set styles map to a new value.

```typescript
styles.setTo( 'border:1px solid blue;margin-top:1px;' );
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L77)

#### Parameters

* `inlineStyle: string`

#### Returns

* `this`

<a id="function-toString">

### `toString() → string`

Returns a normalized style string. Styles are sorted by name.

```typescript
styles.set( 'margin' , '1px' );
styles.set( 'background', '#f00' );

styles.toString(); // -> 'background:#f00;margin:1px;'
```

**Note**: This method supports normalized styles if defined.

```typescript
// Enable 'margin' shorthand processing:
editor.data.addStyleProcessorRules( addMarginStylesRules );

styles.set( 'margin' , '1px' );
styles.set( 'background', '#f00' );
styles.remove( 'margin-top' );
styles.remove( 'margin-right' );

styles.toString(); // -> 'background:#f00;margin-bottom:1px;margin-left:1px;'
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L336)

#### Returns

* `string`

<a id="function-_canMergeFrom">

### `_canMergeFrom( other ) → boolean` _(internal)_

Used by [`_canMergeAttributesFrom`](module_engine_view_element-ViewElement.md#function-_canMergeAttributesFrom) to verify if the given attribute can be merged without conflicts into the attribute.

This method is indirectly used by the [`ViewDowncastWriter`](module_engine_view_downcastwriter-ViewDowncastWriter.md) while down-casting an [`ViewAttributeElement`](module_engine_view_attributeelement-ViewAttributeElement.md) to merge it with other ViewAttributeElement.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L591)

#### Parameters

* `other: StylesMap`

#### Returns

* `boolean`

<a id="function-_clone">

### `_clone() → this` _(internal)_

Clones the attribute value.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L509)

#### Returns

* `this`

<a id="function-_getConsumables">

### `_getConsumables( name? ) → Array<string>` _(internal)_

Returns a list of consumables for the attribute. This includes related styles.

Could be filtered by the given style name.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L559)

#### Parameters

* `name?: string`

#### Returns

* `Array<string>`

<a id="function-_getTokensMatch">

### `_getTokensMatch( tokenPattern, valuePattern ) → Array<string> | undefined` _(internal)_

Used by the [Matcher](module_engine_view_matcher-Matcher.md) to collect matching styles.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L525)

#### Parameters

* `tokenPattern: string | true | RegExp`

  The matched style name pattern.

* `valuePattern: string | true | RegExp`

  The matched style value pattern.

#### Returns

* `Array<string> | undefined`

  An array of matching tokens (style names).

<a id="function-_isMatching">

### `_isMatching( other ) → boolean` _(internal)_

Used by [`_canSubtractAttributesOf`](module_engine_view_element-ViewElement.md#function-_canSubtractAttributesOf) to verify if the given attribute can be fully subtracted from the attribute.

This method is indirectly used by the [`ViewDowncastWriter`](module_engine_view_downcastwriter-ViewDowncastWriter.md) while down-casting an [`ViewAttributeElement`](module_engine_view_attributeelement-ViewAttributeElement.md) to unwrap the ViewAttributeElement.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L626)

#### Parameters

* `other: StylesMap`

#### Returns

* `boolean`

<a id="function-_mergeFrom">

### `_mergeFrom( other ) → void` _(internal)_

Used by [`_mergeAttributesFrom`](module_engine_view_element-ViewElement.md#function-_mergeAttributesFrom) to merge a given attribute into the attribute.

This method is indirectly used by the [`ViewDowncastWriter`](module_engine_view_downcastwriter-ViewDowncastWriter.md) while down-casting an [`ViewAttributeElement`](module_engine_view_attributeelement-ViewAttributeElement.md) to merge it with other ViewAttributeElement.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L609)

#### Parameters

* `other: StylesMap`

#### Returns

* `void`

---

Full index of the CKEditor 5 API reference: [llms.txt](llms.txt)