# MatcherPattern

typedef

An entity that is a valid pattern recognized by a matcher. `MatcherPattern` is used by [`Matcher`](module_engine_view_matcher-Matcher.md) to recognize if a view element fits in a group of view elements described by the pattern.

`MatcherPattern` can be given as a `String`, a `RegExp`, an `Object` or a `Function`.

If `MatcherPattern` is given as a `String` or `RegExp`, it will match any view element that has a matching name:

```typescript
// Match any element with name equal to 'div'.
const pattern = 'div';

// Match any element which name starts on 'p'.
const pattern = /^p/;
```

If `MatcherPattern` is given as an `Object`, all the object's properties will be matched with view element properties. If the view element does not meet all of the object's pattern properties, the match will not happen. Available `Object` matching properties:

Matching view element:

```typescript
// Match view element's name using String:
const pattern = { name: 'p' };

// or by providing RegExp:
const pattern = { name: /^(ul|ol)$/ };

// The name can also be skipped to match any view element with matching attributes:
const pattern = {
	attributes: {
		'title': true
	}
};
```

Matching view element attributes:

```typescript
// Match view element with any attribute value.
const pattern = {
	name: 'p',
	attributes: true
};

// Match view element which has matching attributes (String).
const pattern = {
	name: 'figure',
	attributes: 'title' // Match title attribute (can be empty).
};

// Match view element which has matching attributes (RegExp).
const pattern = {
	name: 'figure',
	attributes: /^data-.*$/ // Match attributes starting with `data-` e.g. `data-foo` with any value (can be empty).
};

// Match view element which has matching attributes (Object).
const pattern = {
	name: 'figure',
	attributes: {
		title: 'foobar',		   // Match `title` attribute with 'foobar' value.
		alt: true,				 // Match `alt` attribute with any value (can be empty).
		'data-type': /^(jpg|png)$/ // Match `data-type` attribute with `jpg` or `png` value.
	}
};

// Match view element which has matching attributes (Array).
const pattern = {
	name: 'figure',
	attributes: [
		'title',	// Match `title` attribute (can be empty).
		/^data-*$/ // Match attributes starting with `data-` e.g. `data-foo` with any value (can be empty).
	]
};

// Match view element which has matching attributes (key-value pairs).
const pattern = {
	name: 'input',
	attributes: [
		{
			key: 'type',					 // Match `type` as an attribute key.
			value: /^(text|number|date)$/	 // Match `text`, `number` or `date` values.
		},
		{
			key: /^data-.*$/,				// Match attributes starting with `data-` e.g. `data-foo`.
			value: true					  // Match any value (can be empty).
		}
	]
};
```

Matching view element styles:

```typescript
// Match view element with any style.
const pattern = {
	name: 'p',
	styles: true
};

// Match view element which has matching styles (String).
const pattern = {
	name: 'p',
	styles: 'color' // Match attributes with `color` style.
};

// Match view element which has matching styles (RegExp).
const pattern = {
	name: 'p',
	styles: /^border.*$/ // Match view element with any border style.
};

// Match view element which has matching styles (Object).
const pattern = {
	name: 'p',
	styles: {
		color: /rgb\((\d{1,3}), (\d{1,3}), (\d{1,3})\)/, // Match `color` in RGB format only.
		'font-weight': 600,							  // Match `font-weight` only if it's `600`.
		'text-decoration': true						  // Match any text decoration.
	}
};

// Match view element which has matching styles (Array).
const pattern = {
	name: 'p',
	styles: [
		'color',	  // Match `color` with any value.
		/^border.*$/ // Match all border properties.
	]
};

// Match view element which has matching styles (key-value pairs).
const pattern = {
	name: 'p',
	styles: [
		{
			key: 'color',								  		// Match `color` as an property key.
			value: /rgb\((\d{1,3}), (\d{1,3}), (\d{1,3})\)/		// Match RGB format only.
		},
		{
			key: /^border.*$/, // Match any border style.
			value: true		// Match any value.
		}
	]
};
```

Matching view element classes:

```typescript
// Match view element with any class.
const pattern = {
	name: 'p',
	classes: true
};

// Match view element which has matching class (String).
const pattern = {
	name: 'p',
	classes: 'highlighted' // Match `highlighted` class.
};

// Match view element which has matching classes (RegExp).
const pattern = {
	name: 'figure',
	classes: /^image-side-(left|right)$/ // Match `image-side-left` or `image-side-right` class.
};

// Match view element which has matching classes (Object).
const pattern = {
	name: 'p',
	classes: {
		highlighted: true, // Match `highlighted` class.
		marker: true	   // Match `marker` class.
	}
};

// Match view element which has matching classes (Array).
const pattern = {
	name: 'figure',
	classes: [
		'image',					// Match `image` class.
		/^image-side-(left|right)$/ // Match `image-side-left` or `image-side-right` class.
	]
};

// Match view element which has matching classes (key-value pairs).
const pattern = {
	name: 'figure',
	classes: [
		{
			key: 'image', // Match `image` class.
			value: true
		},
		{
			key: /^image-side-(left|right)$/, // Match `image-side-left` or `image-side-right` class.
			value: true
		}
	]
};
```

Pattern can combine multiple properties allowing for more complex view element matching:

```typescript
const pattern = {
	name: 'span',
	attributes: [ 'title' ],
	styles: {
		'font-weight': 'bold'
	},
	classes: 'highlighted'
};
```

If `MatcherPattern` is given as a `Function`, the function takes a view element as a first and only parameter and the function should decide whether that element matches. If so, it should return what part of the view element has been matched. Otherwise, the function should return `null`. The returned result will be included in `match` property of the object returned by [`match`](module_engine_view_matcher-Matcher.md#function-match) call.

```typescript
// Match an empty <div> element.
const pattern = element => {
	if ( element.name == 'div' && element.childCount > 0 ) {
		// Return which part of the element was matched.
		return { name: true };
	}

	return null;
};

// Match a <p> element with big font ("heading-like" element).
const pattern = element => {
	if ( element.name == 'p' ) {
		const fontSize = element.getStyle( 'font-size' );
		const size = fontSize.match( /(\d+)/px );

		if ( size && Number( size[ 1 ] ) > 26 ) {
			return { name: true, styles: [ 'font-size' ] };
		}
	}

	return null;
};
```

`MatcherPattern` is defined in a way that it is a superset of [`ViewElementDefinition`](module_engine_view_elementdefinition-ViewElementDefinition.md), that is, every `ElementDefinition` also can be used as a `MatcherPattern`.

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

#### Value

`string | RegExp | MatcherFunctionPattern | MatcherObjectPattern`

---

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