Chips

API for chips

API reference for Angular Material chips

import {MatChipsModule} from '@angular/material/chips';

A material design chips component (named ChipList for its similarity to the List component).

Selector: mat-chip-list

Exported as: matChipList
Properties
Name Description
@Input('aria-orientation')

ariaOrientation: 'horizontal' | 'vertical'

Orientation of the chip list.

@Input()

compareWith: (o1: any, o2: any) => boolean

A function to compare the option values with the selected values. The first argument is a value from an option. The second is a value from the selection. A boolean should be returned.

@Input()

errorStateMatcher: ErrorStateMatcher

An object used to control when error messages are shown.

@Input()

multiple: boolean

Whether the user should be allowed to select multiple chips.

@Input()

selectable: boolean

Whether or not this chip list is selectable. When a chip list is not selectable, the selected states for all the chips inside the chip list are always ignored.

@Output()

change: EventEmitter<MatChipListChange>

Event emitted when the selected chip list value has been changed by the user.

chipBlurChanges: Observable<MatChipEvent>

Combined stream of all of the child chips' blur change events.

chipFocusChanges: Observable<MatChipEvent>

Combined stream of all of the child chips' focus change events.

chipRemoveChanges: Observable<MatChipEvent>

Combined stream of all of the child chips' remove change events.

chipSelectionChanges: Observable<MatChipSelectionChange>

Combined stream of all of the child chips' selection change events.

chips: QueryList<MatChip>

The chip components contained within this chip list.

errorState: boolean

focused: boolean

Whether any chips or the matChipInput inside of this chip-list has focus.

role: string | null

The ARIA role applied to the chip list.

selected: MatChip[] | MatChip

The array of selected chips inside chip list.

stateChanges: Subject<void>

Methods
focus

Focuses the first non-disabled chip in this chip list, or the associated input when there are no eligible chips.

Parameters

options?

FocusOptions

registerInput

Associates an HTML input element with this chip list.

Parameters

inputElement

MatChipTextControl

updateErrorState

Material design styled Chip component. Used inside the MatChipList component.

Selector: mat-basic-chip [mat-basic-chip] mat-chip [mat-chip]

Exported as: matChip
Properties
Name Description
@Input()

color: ThemePalette

Theme color palette for the component.

@Input()

disableRipple: boolean

Whether ripples are disabled.

@Input()

disabled: boolean

Whether the chip is disabled.

@Input()

removable: boolean

Determines whether or not the chip displays the remove styling and emits (removed) events.

@Input()

selectable: boolean

Whether or not the chip is selectable. When a chip is not selectable, changes to its selected state are always ignored. By default a chip is selectable, and it becomes non-selectable if its parent chip list is not selectable.

@Input()

selected: boolean

Whether the chip is selected.

@Input()

value: any

The value of the chip. Defaults to the content inside <mat-chip> tags.

@Output()

destroyed: EventEmitter<MatChipEvent>

Emitted when the chip is destroyed.

@Output()

removed: EventEmitter<MatChipEvent>

Emitted when a chip is to be removed.

@Output()

selectionChange: EventEmitter<MatChipSelectionChange>

Emitted when the chip is selected or deselected.

ariaSelected: string | null

The ARIA selected applied to the chip.

avatar: MatChipAvatar

The chip avatar

chipListSelectable: boolean

Whether the chip list is selectable

defaultColor: ThemePalette | undefined

Default color to fall back to if no value is set.

defaultTabIndex: number

Tabindex to which to fall back to if no value is set.

removeIcon: MatChipRemove

The chip's remove toggler.

trailingIcon: MatChipTrailingIcon

The chip's trailing icon.

Methods
deselect

Deselects the chip.

focus

Allows for programmatic focusing of the chip.

remove

Allows for programmatic removal of the chip. Called by the MatChipList when the DELETE or BACKSPACE keys are pressed.

Informs any listeners of the removal request. Does not remove the chip from the DOM.

select

Selects the chip.

selectViaInteraction

Select this chip and emit selected event

toggleSelected

Toggles the current selected state of this chip.

Parameters

isUserInput

boolean = false

Returns
boolean

Applies proper (click) support and adds styling for use with the Material Design "cancel" icon available at https://material.io/icons/#ic_cancel.

Example:

`<mat-chip>
  <mat-icon matChipRemove>cancel</mat-icon>
</mat-chip>`

You may use a custom icon, but you may need to override the mat-chip-remove positioning styles to properly center the icon within the chip.

Selector: [matChipRemove]

Directive that adds chip-specific behaviors to an input element inside <mat-form-field>. May be placed inside or outside of an <mat-chip-list>.

Selector: input[matChipInputFor]

Exported as: matChipInput, matChipInputFor
Properties
Name Description
@Input('matChipInputAddOnBlur')

addOnBlur: boolean

Whether or not the chipEnd event will be emitted when the input is blurred.

@Input('matChipInputFor')

chipList: MatChipList

Register input for chip list

@Input()

disabled: boolean

Whether the input is disabled.

@Input()

id: string

Unique id for the input.

@Input()

placeholder: string

The input's placeholder text.

@Input('matChipInputSeparatorKeyCodes')

separatorKeyCodes: readonly number[] | ReadonlySet<number>

The list of key codes that will trigger a chipEnd event.

Defaults to [ENTER].

@Output('matChipInputTokenEnd')

chipEnd: EventEmitter<MatChipInputEvent>

Emitted when a chip is to be added.

empty: boolean

Whether the input is empty.

focused: boolean

Whether the control is focused.

Methods
focus

Focuses the input.

Parameters

options?

FocusOptions

Change event object that is emitted when the chip list value has changed.

Properties
Name Description

source: MatChipList

Chip list that emitted the event.

value: any

Value of the chip list when the event was emitted.

Event object emitted by MatChip when selected or deselected.

Properties
Name Description

isUserInput: false

Whether the selection change was a result of a user interaction.

selected: boolean

Whether the chip that emitted the event is selected.

source: MatChip

Reference to the chip that emitted the event.

Represents an event fired on an individual mat-chip.

Properties
Name Description

chip: MatChip

The chip the event was fired on.

Represents an input event on a matChipInput.

Properties
Name Description

input: HTMLInputElement

The native <input> element that the event is being fired for.

value: string

The value of the input.

Default options, for the chips module, that can be overridden.

Properties
Name Description

separatorKeyCodes: readonly number[] | ReadonlySet<number>

The list of key codes that will trigger a chipEnd event.

Injection token that can be used to reference instances of MatChipRemove. It serves as alternative token to the actual MatChipRemove class which could cause unnecessary retention of the class and its directive metadata.

const MAT_CHIP_REMOVE: InjectionToken<MatChipRemove>;

Injection token that can be used to reference instances of MatChipAvatar. It serves as alternative token to the actual MatChipAvatar class which could cause unnecessary retention of the class and its directive metadata.

const MAT_CHIP_AVATAR: InjectionToken<MatChipAvatar>;

Injection token that can be used to reference instances of MatChipTrailingIcon. It serves as alternative token to the actual MatChipTrailingIcon class which could cause unnecessary retention of the class and its directive metadata.

const MAT_CHIP_TRAILING_ICON: InjectionToken<MatChipTrailingIcon>;

Injection token to be used to override the default options for the chips module.

const MAT_CHIPS_DEFAULT_OPTIONS: InjectionToken<MatChipsDefaultOptions>;

API reference for Angular Material chips-testing

import {MatChipHarness} from '@angular/material/chips/testing';

Harness for interacting with a standard Angular Material chip in tests.

Methods
async
getRemoveButton

Gets the remove button inside of a chip.

Parameters

filter

ChipRemoveHarnessFilters = {}

Optionally filters which chips are included.

Returns
Promise<MatChipRemoveHarness>

async
getText

Gets the text of the chip.

Returns
Promise<string>

async
host

Gets a Promise for the TestElement representing the host element of the component.

Returns
Promise<TestElement>

async
isDisabled

Whether the chip is disabled.

Returns
Promise<boolean>

async
remove

Removes the given chip. Only applies if it's removable.

Returns
Promise<void>

Promise that resolves when the action completes.

Deprecated
async
deselect

Deselects the given chip. Only applies if it's selectable.

Returns
Promise<void>

Promise that resolves when the action completes.

Deprecated
async
isSelected

Whether the chip is selected.

Returns
Promise<boolean>

Deprecated
async
select

Selects the given chip. Only applies if it's selectable.

Returns
Promise<void>

Promise that resolves when the action completes.

Deprecated
async
toggle

Toggles the selected state of the given chip. Only applies if it's selectable.

Returns
Promise<void>

Promise that resolves when the action completes.

Harness for interacting with a standard chip list in tests.

Methods
async
getChips

Gets the list of chips inside the chip list.

Parameters

filter

ChipHarnessFilters = {}

Optionally filters which chips are included.

Returns
Promise<MatChipHarness[]>

async
getInput

Gets the MatChipInput inside the chip list.

Parameters

filter

ChipInputHarnessFilters = {}

Optionally filters which chip input is included.

Returns
Promise<MatChipInputHarness>

async
getOrientation

Gets whether the orientation of the chip list.

Returns
Promise<'horizontal' | 'vertical'>

async
host

Gets a Promise for the TestElement representing the host element of the component.

Returns
Promise<TestElement>

async
isDisabled

Gets whether the chip list is disabled.

Returns
Promise<boolean>

async
isInvalid

Gets whether the chip list is invalid.

Returns
Promise<boolean>

async
isMultiple

Gets whether the chip list is in multi selection mode.

Returns
Promise<boolean>

async
isRequired

Gets whether the chip list is required.

Returns
Promise<boolean>

Deprecated
async
selectChips

Selects a chip inside the chip list.

Parameters

filter

ChipHarnessFilters = {}

An optional filter to apply to the child chips. All the chips matching the filter will be selected.

Returns
Promise<void>

Promise that resolves when the action completes.

Harness for interacting with a standard Material chip inputs in tests.

Methods
async
blur

Blurs the input and returns a promise that indicates when the action is complete.

Returns
Promise<void>

Promise that resolves when the action completes.

async
focus

Focuses the input and returns a promise that indicates when the action is complete.

Returns
Promise<void>

Promise that resolves when the action completes.

async
getPlaceholder

Gets the placeholder of the input.

Returns
Promise<string>

async
getValue

Gets the value of the input.

Returns
Promise<string>

async
host

Gets a Promise for the TestElement representing the host element of the component.

Returns
Promise<TestElement>

async
isDisabled

Whether the input is disabled.

Returns
Promise<boolean>

async
isFocused

Whether the input is focused.

Returns
Promise<boolean>

async
isRequired

Whether the input is required.

Returns
Promise<boolean>

async
sendSeparatorKey

Sends a chip separator key to the input element.

Parameters

key

string | TestKey

Returns
Promise<void>

Promise that resolves when the action completes.

async
setValue

Sets the value of the input. The value will be set by simulating keypresses that correspond to the given value.

Parameters

newValue

string

Returns
Promise<void>

Promise that resolves when the action completes.

Harness for interacting with a standard Material chip remove button in tests.

Methods
async
click

Clicks the remove button.

Returns
Promise<void>

Promise that resolves when the action completes.

async
host

Gets a Promise for the TestElement representing the host element of the component.

Returns
Promise<TestElement>

A set of criteria that can be used to filter a list of MatChipHarness instances.

Properties
Name Description

text: string | RegExp

Only find instances whose text matches the given value.

Deprecated

selected: boolean

Only find chip instances whose selected state matches the given value.

A set of criteria that can be used to filter a list of MatChipListHarness instances.

A set of criteria that can be used to filter a list of MatChipListInputHarness instances.

Properties
Name Description

placeholder: string | RegExp

Filters based on the placeholder text of the input.

value: string | RegExp

Filters based on the value of the input.

A set of criteria that can be used to filter a list of MatChipRemoveHarness instances.