API reference for Angular Material chips

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

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.

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.

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

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.

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.

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.

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.

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[]

Avatar image within a chip.

Selector: mat-chip-avatar [matChipAvatar]

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

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

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

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

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.

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.

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.

Represents an event fired on an individual mat-chip.

Properties
Name Description

chip: MatChip

The chip the event was fired on.

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

Properties
Name Description

value: string

The final edit value.

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.

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.

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[]

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

const MAT_CHIPS_DEFAULT_OPTIONS: InjectionToken<MatChipsDefaultOptions>;

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

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

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

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

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

const MAT_CHIP: InjectionToken<unknown>;