API reference for Angular Material chips

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

Components

`MatChip`

Material design styled Chip base component. Used inside the MatChipSet component.

Extended by MatChipOption and MatChipRow for different interaction patterns.

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

Exported as: matChip

Properties

Name	Description
@Input('aria-description') `ariaDescription: string \| null`	ARIA description for the content of the chip.
@Input('aria-label') `ariaLabel: string \| null`	ARIA label for the content of the chip.
@Input() `color: string \| null`	Theme color of the chip. This API is supported in M2 themes only, it has no effect in M3 themes. For color customization in M3, see https://material.angular.dev/components/chips/styling. For information on applying color variants in M3, see https://material.angular.dev/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants
@Input({ transform: booleanAttribute }) `disableRipple: boolean`	Whether the ripple effect is disabled or not.
@Input({ transform: booleanAttribute }) `disabled: boolean`	Whether the chip is disabled.
@Input({ transform: booleanAttribute }) `highlighted: boolean`	Colors the chip for emphasis as if it were selected.
@Input() `id: string`	A unique id for the chip. If none is supplied, it will be auto-generated.
@Input({ transform: booleanAttribute }) `removable: boolean`	Determines whether or not the chip displays the remove styling and emits (removed) events.
@Input() `role: string \| null`	Role for the root of the chip.
@Input() `value: any`	The value of the chip. Defaults to the content inside the `mat-mdc-chip-action-label` element.
@Output() `destroyed: EventEmitter<MatChipEvent>`	Emitted when the chip is destroyed.
@Output() `removed: EventEmitter<MatChipEvent>`	Emitted when a chip is to be removed.
`basicChipAttrName: 'mat-basic-chip'`	The unstyled chip selector for this component.
`editIcon: MatChipEdit`	The chip's leading edit icon.
`leadingIcon: MatChipAvatar`	The chip's leading icon.
`primaryAction: MatChipAction`	Action receiving the primary set of user interactions.
`removeIcon: MatChipRemove`	The chip's trailing remove icon.
`trailingIcon: MatChipTrailingIcon`	The chip's trailing icon.

Methods

focus
Allows for programmatic focusing of the chip.

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

remove

Allows for programmatic removal of the chip.

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

`MatChipOption` extends MatChip

An extension of the MatChip component that supports chip selection. Used with MatChipListbox.

Unlike other chips, the user can focus on disabled chip options inside a MatChipListbox. The user cannot click disabled chips.

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

Properties

Name	Description
@Input('aria-description') `ariaDescription: string \| null`	ARIA description for the content of the chip.
@Input('aria-label') `ariaLabel: string \| null`	ARIA label for the content of the chip.
@Input() `color: string \| null`	Theme color of the chip. This API is supported in M2 themes only, it has no effect in M3 themes. For color customization in M3, see https://material.angular.dev/components/chips/styling. For information on applying color variants in M3, see https://material.angular.dev/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants
@Input({ transform: booleanAttribute }) `disableRipple: boolean`	Whether the ripple effect is disabled or not.
@Input({ transform: booleanAttribute }) `disabled: boolean`	Whether the chip is disabled.
@Input({ transform: booleanAttribute }) `highlighted: boolean`	Colors the chip for emphasis as if it were selected.
@Input() `id: string`	A unique id for the chip. If none is supplied, it will be auto-generated.
@Input({ transform: booleanAttribute }) `removable: boolean`	Determines whether or not the chip displays the remove styling and emits (removed) events.
@Input() `role: string \| null`	Role for the root of the chip.
@Input({ transform: booleanAttribute }) `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 an option chip is selectable, and it becomes non-selectable if its parent chip list is not selectable.
@Input({ transform: booleanAttribute }) `selected: boolean`	Whether the chip is selected.
@Input() `value: any`	The value of the chip. Defaults to the content inside the `mat-mdc-chip-action-label` element.
@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. Conforms to WAI ARIA best practices for listbox interaction patterns. From WAI ARIA Listbox authoring practices guide: "If any options are selected, each selected option has either aria-selected or aria-checked set to true. All options that are selectable but not selected have either aria-selected or aria-checked set to false." Set `aria-selected="false"` on not-selected listbox options that are selectable to fix VoiceOver reading every option as "selected" (#25736).
`basicChipAttrName: 'mat-basic-chip-option'`	The unstyled chip selector for this component.
`chipListSelectable: boolean`	Whether the chip list is selectable.
`editIcon: MatChipEdit`	The chip's leading edit icon.
`leadingIcon: MatChipAvatar`	The chip's leading icon.
`primaryAction: MatChipAction`	Action receiving the primary set of user interactions.
`removeIcon: MatChipRemove`	The chip's trailing remove icon.
`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. Informs any listeners of the removal request. Does not remove the chip from the DOM.

remove

Allows for programmatic removal of the chip.

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

select
Selects the chip.

selectViaInteraction
Selects this chip and emits userInputSelection event

toggleSelected
Toggles the current selected state of this chip.
Parameters
isUserInput `boolean = false`
Returns
`boolean`

`MatChipRow` extends MatChip

An extension of the MatChip component used with MatChipGrid and the matChipInputFor directive.

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

Properties

Name	Description
@Input('aria-description') `ariaDescription: string \| null`	ARIA description for the content of the chip.
@Input('aria-label') `ariaLabel: string \| null`	ARIA label for the content of the chip.
@Input() `color: string \| null`	Theme color of the chip. This API is supported in M2 themes only, it has no effect in M3 themes. For color customization in M3, see https://material.angular.dev/components/chips/styling. For information on applying color variants in M3, see https://material.angular.dev/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants
@Input({ transform: booleanAttribute }) `disableRipple: boolean`	Whether the ripple effect is disabled or not.
@Input({ transform: booleanAttribute }) `disabled: boolean`	Whether the chip is disabled.
@Input() `editable: boolean`
@Input({ transform: booleanAttribute }) `highlighted: boolean`	Colors the chip for emphasis as if it were selected.
@Input() `id: string`	A unique id for the chip. If none is supplied, it will be auto-generated.
@Input({ transform: booleanAttribute }) `removable: boolean`	Determines whether or not the chip displays the remove styling and emits (removed) events.
@Input() `role: string \| null`	Role for the root of the chip.
@Input() `value: any`	The value of the chip. Defaults to the content inside the `mat-mdc-chip-action-label` element.
@Output() `destroyed: EventEmitter<MatChipEvent>`	Emitted when the chip is destroyed.
@Output() `edited: EventEmitter<MatChipEditedEvent>`	Emitted when the chip is edited.
@Output() `removed: EventEmitter<MatChipEvent>`	Emitted when a chip is to be removed.
`basicChipAttrName: 'mat-basic-chip-row'`
`contentEditInput: MatChipEditInput`	The projected chip edit input.
`defaultEditInput: MatChipEditInput`	The default chip edit input that is used if none is projected into this chip row.
`editIcon: MatChipEdit`	The chip's leading edit icon.
`leadingIcon: MatChipAvatar`	The chip's leading icon.
`primaryAction: MatChipAction`	Action receiving the primary set of user interactions.
`removeIcon: MatChipRemove`	The chip's trailing remove icon.
`trailingIcon: MatChipTrailingIcon`	The chip's trailing icon.

Methods

focus
Allows for programmatic focusing of the chip.

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

remove

Allows for programmatic removal of the chip.

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

`MatChipSet`

Basic container component for the MatChip component.

Extended by MatChipListbox and MatChipGrid for different interaction patterns.

Selector: mat-chip-set

Properties

Name	Description
@Input({ transform: booleanAttribute }) `disabled: boolean`	Whether the chip set is disabled.
@Input() `role: string \| null`	The ARIA role applied to the chip set.
`chipDestroyedChanges: Observable<MatChipEvent>`	Combined stream of all of the child chips' destroy events.
`chipFocusChanges: Observable<MatChipEvent>`	Combined stream of all of the child chips' focus events.
`chipRemovedChanges: Observable<MatChipEvent>`	Combined stream of all of the child chips' remove events.
`empty: boolean`	Whether the chip list contains chips or not.
`focused: boolean`	Whether any of the chips inside of this chip-set has focus.

Methods

focus
Dummy method for subclasses to override. Base chip set cannot be focused.

`MatChipListbox` extends MatChipSet

An extension of the MatChipSet component that supports chip selection. Used with MatChipOption chips.

Selector: mat-chip-listbox

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({ transform: booleanAttribute }) `disabled: boolean`	Whether the chip set is disabled.
@Input({ transform: booleanAttribute }) `hideSingleSelectionIndicator: boolean`	Whether checkmark indicator for single-selection options is hidden.
@Input({ transform: booleanAttribute }) `multiple: boolean`	Whether the user should be allowed to select multiple chips.
@Input({ transform: booleanAttribute }) `required: boolean`	Whether this chip listbox is required.
@Input() `role: string \| null`	The ARIA role applied to the chip set.
@Input({ transform: booleanAttribute }) `selectable: boolean`	Whether or not this chip listbox is selectable. When a chip listbox is not selectable, the selected states for all the chips inside the chip listbox are always ignored.
@Input() `value: any`	The value of the listbox, which is the combined value of the selected chips.
@Output() `change: EventEmitter<MatChipListboxChange>`	Event emitted when the selected chip listbox value has been changed by the user.
`chipBlurChanges: Observable<MatChipEvent>`	Combined stream of all of the child chips' blur events.
`chipDestroyedChanges: Observable<MatChipEvent>`	Combined stream of all of the child chips' destroy events.
`chipFocusChanges: Observable<MatChipEvent>`	Combined stream of all of the child chips' focus events.
`chipRemovedChanges: Observable<MatChipEvent>`	Combined stream of all of the child chips' remove events.
`chipSelectionChanges: Observable<MatChipSelectionChange>`	Combined stream of all of the child chips' selection change events.
`empty: boolean`	Whether the chip list contains chips or not.
`focused: boolean`	Whether any of the chips inside of this chip-set has focus.
`selected: MatChipOption[] \| MatChipOption`	The array of selected chips inside the chip listbox.

Methods

focus
Focuses the first selected chip in this chip listbox, or the first non-disabled chip when there are no selected chips.

`MatChipGrid` extends MatChipSet

An extension of the MatChipSet component used with MatChipRow chips and the matChipInputFor directive.

Selector: mat-chip-grid

Properties

Name	Description
@Input() `errorStateMatcher: ErrorStateMatcher`	An object used to control when error messages are shown.
@Input() `role: string \| null`	The ARIA role applied to the chip set.
@Output() `change: EventEmitter<MatChipGridChange>`	Emits when the chip grid value has been changed by the user.
`chipBlurChanges: Observable<MatChipEvent>`	Combined stream of all of the child chips' blur events.
`chipDestroyedChanges: Observable<MatChipEvent>`	Combined stream of all of the child chips' destroy events.
`chipFocusChanges: Observable<MatChipEvent>`	Combined stream of all of the child chips' focus events.
`chipRemovedChanges: Observable<MatChipEvent>`	Combined stream of all of the child chips' remove events.
`errorState: boolean`	Whether the chip grid is in an error state.
`focused: boolean`	Whether any chips or the matChipInput inside of this chip-grid has focus.
`ngControl: inject(NgControl, { optional: true, self: true })!`

Methods

focus
Focuses the first chip in this chip grid, or the associated input when there are no eligible chips.

registerInput
Associates an HTML input element with this chip grid.
Parameters
inputElement `MatChipTextControl`

updateErrorState
Refreshes the error state of the chip grid.

Directives

`MatChipInput`

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

Selector: input[matChipInputFor]

Exported as: matChipInput, matChipInputFor

Properties

Name	Description
@Input({ alias: 'matChipInputAddOnBlur', transform: booleanAttribute }) `addOnBlur: boolean`	Whether or not the chipEnd event will be emitted when the input is blurred.
@Input('matChipInputFor') `chipGrid: MatChipGrid`	Register input for chip list
@Input({ transform: booleanAttribute }) `disabled: boolean`	Whether the input is disabled.
@Input({ alias: 'matChipInputDisabledInteractive', transform: booleanAttribute }) `disabledInteractive: boolean`	Whether the input should remain interactive when it is disabled.
@Input() `id: string`	Unique id for the input.
@Input() `placeholder: string`	The input's placeholder text.
@Input({ transform: booleanAttribute }) `readonly: boolean`	Whether the input is readonly.
@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.
`inputElement: HTMLInputElement`	The native input element to which this directive is attached.

Methods

clear
Clears the input

focus
Focuses the input.

setDescribedByIds
Parameters
ids `string[]`

`MatChipAvatar`

Avatar image within a chip.

Selector: mat-chip-avatar [matChipAvatar]

`MatChipTrailingIcon`

Non-interactive trailing icon in a chip.

Selector: mat-chip-trailing-icon [matChipTrailingIcon]

Properties

Name	Description
@Input({ transform: booleanAttribute }) `disabled: boolean`	Whether the action is disabled.
`isInteractive: false`	MDC considers all trailing actions as a remove icon, but we support non-interactive trailing icons.

Methods

focus

`MatChipEdit`

Directive to edit the parent chip when the leading action icon is clicked or when the ENTER key is pressed on it.

Recommended for use with the Material Design "edit" icon available at https://material.io/icons/#ic_edit.

Example:

<mat-chip>
  <button matChipEdit aria-label="Edit">
    <mat-icon>edit</mat-icon>
  </button>
</mat-chip>

Selector: [matChipEdit]

Properties

Name	Description
@Input({ transform: booleanAttribute }) `disabled: boolean`	Whether the action is disabled.
@Input() `isInteractive: true`	Whether the action is interactive.

Methods

focus

`MatChipRemove`

Directive to remove the parent chip when the trailing icon is clicked or when the ENTER key is pressed on it.

Recommended 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>

Selector: [matChipRemove]

Properties

Name	Description
@Input({ transform: booleanAttribute }) `disabled: boolean`	Whether the action is disabled.
@Input() `isInteractive: true`	Whether the action is interactive.

Methods

focus

`MatChipEditInput`

A directive that makes a span editable and exposes functions to modify and retrieve the element's contents.

Selector: span[matChipEditInput]

Methods

getNativeElement
Returns
`HTMLElement`

getValue
Returns
`string`

initialize
Parameters
initialValue `string`

setValue
Parameters
value `string`

Classes

`MatChipSelectionChange`

Event object emitted by MatChipOption 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: MatChipOption`	Reference to the chip that emitted the event.

`MatChipListboxChange`

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

Properties

Name	Description
`source: MatChipListbox`	Chip listbox that emitted the event.
`value: any`	Value of the chip listbox when the event was emitted.

`MatChipGridChange`

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

Properties

Name	Description
`source: MatChipGrid`	Chip grid that emitted the event.
`value: any`	Value of the chip grid when the event was emitted.

Interfaces

`MatChipEvent`

Represents an event fired on an individual mat-chip.

Properties

Name	Description
`chip: MatChip`	The chip the event was fired on.

`MatChipEditedEvent`

Represents an event fired on an individual mat-chip when it is edited.

Properties

Name	Description
`value: string`	The final edit value.

`MatChipInputEvent`

Represents an input event on a matChipInput.

Properties

Name	Description
`chipInput: MatChipInput`	Reference to the chip input that emitted the event.
`value: string`	The value of the input.
Deprecated `input: HTMLInputElement`	The native `<input>` element that the event is being fired for.

`MatChipsDefaultOptions`

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

Properties

Name	Description
`hideSingleSelectionIndicator: boolean`	Whether icon indicators should be hidden for single-selection.
`inputDisabledInteractive: boolean`	Whether the chip input should be interactive while disabled by default.
`separatorKeyCodes: readonly number[] \| ReadonlySet<number>`	The list of key codes that will trigger a chipEnd event.

`MatChipTextControl`

Interface for a text control that is used to drive interaction with a mat-chip-list.

Properties

Name	Description
`describedByIds: string[]`	Gets the list of ids the input is described by.
`empty: boolean`	Whether the text control is empty.
`focused: boolean`	Whether the text control has browser focus.
`id: string`	Unique identifier for the text control.
`placeholder: string`	The text control's placeholder text.

Methods

focus
Focuses the text control.

setDescribedByIds
Sets the list of ids the input is described by.
Parameters
ids `string[]`

Constants

`MAT_CHIPS_DEFAULT_OPTIONS`

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

const MAT_CHIPS_DEFAULT_OPTIONS: InjectionToken<MatChipsDefaultOptions>;

`MAT_CHIP_AVATAR`

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<unknown>;

`MAT_CHIP_TRAILING_ICON`

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<unknown>;

`MAT_CHIP_EDIT`

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

const MAT_CHIP_EDIT: InjectionToken<unknown>;

`MAT_CHIP_REMOVE`

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<unknown>;

`MAT_CHIP`

Injection token used to avoid a circular dependency between the MatChip and MatChipAction.

const MAT_CHIP: InjectionToken<unknown>;

API reference for Angular Material chips

Components

MatChip

Properties

Methods

MatChipOption extends MatChip

Properties

Methods

MatChipRow extends MatChip

Properties

Methods

MatChipSet

Properties

Methods

MatChipListbox extends MatChipSet

Properties

Methods

MatChipGrid extends MatChipSet

Properties

Methods

Directives

MatChipInput

Properties

Methods

MatChipAvatar

MatChipTrailingIcon

Properties

Methods

MatChipEdit

Properties

Methods

MatChipRemove

Properties

Methods

MatChipEditInput

Methods

Classes

MatChipSelectionChange

Properties

MatChipListboxChange

Properties

MatChipGridChange

Properties

Interfaces

MatChipEvent

Properties

MatChipEditedEvent

Properties

MatChipInputEvent

Properties

MatChipsDefaultOptions

Properties

MatChipTextControl

Properties

Methods

Constants

MAT_CHIPS_DEFAULT_OPTIONS

MAT_CHIP_AVATAR

MAT_CHIP_TRAILING_ICON

MAT_CHIP_EDIT

MAT_CHIP_REMOVE

MAT_CHIP

`MatChip`

`MatChipOption` extends MatChip

`MatChipRow` extends MatChip

`MatChipSet`

`MatChipListbox` extends MatChipSet

`MatChipGrid` extends MatChipSet

`MatChipInput`

`MatChipAvatar`

`MatChipTrailingIcon`

`MatChipEdit`

`MatChipRemove`

`MatChipEditInput`

`MatChipSelectionChange`

`MatChipListboxChange`

`MatChipGridChange`

`MatChipEvent`

`MatChipEditedEvent`

`MatChipInputEvent`

`MatChipsDefaultOptions`

`MatChipTextControl`

`MAT_CHIPS_DEFAULT_OPTIONS`

`MAT_CHIP_AVATAR`

`MAT_CHIP_TRAILING_ICON`

`MAT_CHIP_EDIT`

`MAT_CHIP_REMOVE`

`MAT_CHIP`