# Matcher

class

View matcher class. Instance of this class can be used to find [elements](module_engine_view_element-ViewElement.md) that match given pattern.

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

<a id="properties">

## Properties

<a id="member-_patterns">

### `_patterns: Array<MatcherFunctionPattern | MatcherObjectPattern>` _(private)_

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

<a id="methods">

## Methods

<a id="function-constructor">

### `constructor( pattern )`

Creates new instance of Matcher.

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

#### Parameters

* `pattern: Array<MatcherPattern>`

  Match patterns. See [add method](#function-add) for more information.

<a id="function-add">

### `add( pattern ) → void`

Adds pattern or patterns to matcher instance.

```typescript
// String.
matcher.add( 'div' );

// Regular expression.
matcher.add( /^\w/ );

// Single class.
matcher.add( {
	classes: 'foobar'
} );
```

See [`MatcherPattern`](module_engine_view_matcher-MatcherPattern.md) for more examples.

Multiple patterns can be added in one call:

```typescript
matcher.add( 'div', { classes: 'foobar' } );
```

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

#### Parameters

* `pattern: Array<MatcherPattern>`

  Object describing pattern details. If string or regular expression is provided it will be used to match element's name. Pattern can be also provided in a form of a function - then this function will be called with each [element](module_engine_view_element-ViewElement.md) as a parameter. Function's return value will be stored under `match` key of the object returned from [match](#function-match) or [matchAll](#function-matchAll) methods.

#### Returns

* `void`

<a id="function-getElementName">

### `getElementName() → string | null`

Returns the name of the element to match if there is exactly one pattern added to the matcher instance and it matches element name defined by `string` (not `RegExp`). Otherwise, returns `null`.

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

#### Returns

* `string | null`

  Element name trying to match.

<a id="function-match">

### `match( element ) → MatchResult | null`

Matches elements for currently stored patterns. Returns match information about first found [element](module_engine_view_element-ViewElement.md), otherwise returns `null`.

Example of returned object:

```typescript
{
	element: <instance of found element>,
	pattern: <pattern used to match found element>,
	match: {
		name: true,
		attributes: [
			[ 'title' ],
			[ 'href' ],
			[ 'class', 'foo' ],
			[ 'style', 'color' ],
			[ 'style', 'position' ]
		]
	}
}
```

You could use the `match` field from the above returned object as an input for the [`ViewConsumable#test()`](module_engine_conversion_viewconsumable-ViewConsumable.md#function-test) and [`ViewConsumable#consume()`](module_engine_conversion_viewconsumable-ViewConsumable.md#function-consume) methods.

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

#### Parameters

* `element: Array<ViewElement>`

  View element to match against stored patterns.

#### Returns

* `MatchResult | null`

  The match information about found element or `null`.

#### Related:

* [Matcher#add](#function-add)
* [Matcher#matchAll](#function-matchAll)

<a id="function-matchAll">

### `matchAll( element ) → Array<MatchResult> | null`

Matches elements for currently stored patterns. Returns array of match information with all found [elements](module_engine_view_element-ViewElement.md). If no element is found - returns `null`.

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

#### Parameters

* `element: Array<ViewElement>`

  View element to match against stored patterns.

#### Returns

* `Array<MatchResult> | null`

  Array with match information about found elements or `null`. For more information see [match method](#function-match) description.

#### Related:

* [Matcher#add](#function-add)
* [Matcher#match](#function-match)

<a id="function-_isElementMatching">

### `_isElementMatching( element, pattern ) → Match | null` _(private)_

Returns match information if [element](module_engine_view_element-ViewElement.md) is matching provided pattern. If element cannot be matched to provided pattern - returns `null`.

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

#### Parameters

* `element: ViewElement`
* `pattern: MatcherFunctionPattern | MatcherObjectPattern`

#### Returns

* `Match | null`

  Returns object with match information or null if element is not matching.

---

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