Skip to content

Docs aria guides sync #68967

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JeanMeche wants to merge 1 commit into
base: 22.0.x
Choose a base branch
from
+60 −29
Open

Docs aria guides sync #68967

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 60 additions & 29 deletions adev/src/content/guide/aria/autocomplete.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

An accessible input field that filters and suggests options as users type, helping them find and select values from a list.

<!-- <docs-tab-group>
<docs-tab-group>
<docs-tab label="Basic">
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/autocomplete/src/basic/app/app.ts">
<docs-code header="app.ts" path="adev/src/content/examples/aria/autocomplete/src/basic/app/app.ts"/>
Expand All @@ -29,7 +29,7 @@ An accessible input field that filters and suggests options as users type, helpi
<docs-code header="app.css" path="adev/src/content/examples/aria/autocomplete/src/basic/retro/app/app.css"/>
</docs-code-multifile>
</docs-tab>
</docs-tab-group> -->
</docs-tab-group>

## Usage

Expand All @@ -52,7 +52,7 @@ Angular's autocomplete provides a fully accessible combobox implementation with:

- **Keyboard Navigation** - Navigate options with arrow keys, select with Enter, close with Escape
- **Screen Reader Support** - Built-in ARIA attributes for assistive technologies
- **Three Filter Modes** - Choose between auto-select, manual selection, or highlighting behavior
- **Dynamic Highlight Behavior** - Built-in support for inline selection suggestions
- **Signal-Based Reactivity** - Reactive state management using Angular signals
- **Popover API Integration** - Leverages the native HTML Popover API for optimal positioning
- **Bidirectional Text Support** - Automatically handles right-to-left (RTL) languages
Expand All @@ -63,7 +63,7 @@ Angular's autocomplete provides a fully accessible combobox implementation with:

Users typing partial text expect immediate confirmation that their input matches an available option. Auto-select mode updates the input value to match the first filtered option as users type, reducing the number of keystrokes needed and providing instant feedback that their search is on the right track.

<!-- <docs-tab-group>
<docs-tab-group>
<docs-tab label="Basic">
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/autocomplete/src/basic/app/app.ts">
<docs-code header="app.ts" path="adev/src/content/examples/aria/autocomplete/src/basic/app/app.ts"/>
Expand All @@ -87,13 +87,13 @@ Users typing partial text expect immediate confirmation that their input matches
<docs-code header="app.css" path="adev/src/content/examples/aria/autocomplete/src/basic/retro/app/app.css"/>
</docs-code-multifile>
</docs-tab>
</docs-tab-group> -->
</docs-tab-group>

### Manual selection mode

Manual selection mode keeps the typed text unchanged while users navigate the suggestion list, preventing confusion from automatic updates. The input only changes when users explicitly confirm their choice with Enter or a click.

<!-- <docs-tab-group>
<docs-tab-group>
<docs-tab label="Basic">
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/autocomplete/src/manual/app/app.ts">
<docs-code header="app.ts" path="adev/src/content/examples/aria/autocomplete/src/manual/app/app.ts"/>
Expand All @@ -117,13 +117,13 @@ Manual selection mode keeps the typed text unchanged while users navigate the su
<docs-code header="app.css" path="adev/src/content/examples/aria/autocomplete/src/manual/retro/app/app.css"/>
</docs-code-multifile>
</docs-tab>
</docs-tab-group> -->
</docs-tab-group>

### Highlight mode

Highlight mode allows the user to navigate options with arrow keys without changing the input value as they browse until they explicitly select a new option with Enter or click.

<!-- <docs-tab-group>
<docs-tab-group>
<docs-tab label="Basic">
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/autocomplete/src/highlight/app/app.ts">
<docs-code header="app.ts" path="adev/src/content/examples/aria/autocomplete/src/highlight/app/app.ts"/>
Expand All @@ -147,44 +147,75 @@ Highlight mode allows the user to navigate options with arrow keys without chang
<docs-code header="app.css" path="adev/src/content/examples/aria/autocomplete/src/highlight/retro/app/app.css"/>
</docs-code-multifile>
</docs-tab>
</docs-tab-group> -->
</docs-tab-group>

## APIs

### Combobox Directive

The `ngCombobox` directive provides the container for autocomplete functionality.
The `ngCombobox` directive is applied directly onto the editable text `<input>` or `<textarea>` to manage keyboard triggers and popover states.

#### Inputs

| Property | Type | Default | Description |
| ------------ | ---------------------------------------------- | ---------- | ------------------------------------------------- |
| `filterMode` | `'auto-select'` \| `'manual'` \| `'highlight'` | `'manual'` | Controls selection behavior |
| `disabled` | `boolean` | `false` | Disables the combobox |
| `firstMatch` | `string` | - | The value of the first matching item in the popup |
| Property | Type | Default | Description |
| ------------------ | --------------------- | ----------- | --------------------------------------------------------------- |
| `disabled` | `boolean` | `false` | Disables the combobox |
| `softDisabled` | `boolean` | `true` | Focusable when disabled |
| `inlineSuggestion` | `string \| undefined` | `undefined` | Displays an inline completion suggestion for autocomplete modes |

#### Outputs
#### Models

| Property | Type | Description |
| ---------- | ----------------- | ----------------------------------------------------- |
| `expanded` | `Signal<boolean>` | Signal indicating whether the popup is currently open |
| Property | Type | Default | Description |
| ---------- | ---------------------- | ------- | ----------------------------------------------------------------- |
| `value` | `ModelSignal<string>` | `''` | Two-way bindable value of the input using `[(value)]` |
| `expanded` | `ModelSignal<boolean>` | `false` | Two-way bindable expanded state of the popup using `[(expanded)]` |

### ComboboxInput Directive
---

The `ngComboboxInput` directive connects an input element to the combobox.
### ComboboxPopup Directive

#### Model
A structural directive applied to `<ng-template>` to mark the container used as the popup.

| Property | Type | Description |
| -------- | -------- | ------------------------------------------------------------ |
| `value` | `string` | Two-way bindable string value of the input using `[(value)]` |
#### Inputs

| Property | Type | Description |
| ---------- | ---------- | ------------------------------------------- |
| `combobox` | `Combobox` | Required reference to the parent `Combobox` |

---

### ComboboxWidget Directive

Applied to the popup content container to bridge active-descendant focus changes to the input trigger.

#### Inputs

| Property | Type | Description |
| ------------------ | --------------------- | --------------------------------------------------------------------------------- |
| `activeDescendant` | `string \| undefined` | The ID of the currently active descendant (bound to `listbox.activeDescendant()`) |

---

### Listbox Directives

Autocomplete suggestion lists use the standard standalone listbox directives.

#### Inputs

| Property | Type | Default | Description |
| --------------- | ---------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------- |
| `selectionMode` | `'follow'` \| `'explicit'` | `'follow'` | In manual/explicit mode, updates are committed explicitly on click/Enter rather than following focus |
| `focusMode` | `'roving'` \| `'activedescendant'` | `'roving'` | Set to `'activedescendant'` so browser focus stays on the trigger input |
| `tabIndex` | `number` | `0` | Set to `-1` to prevent keyboard tab focus from entering the popup listbox container |

### ComboboxPopupContainer Directive
#### Models

The `ngComboboxPopupContainer` directive wraps the popup content and manages its display.
| Property | Type | Description |
| -------- | -------------------- | ----------------------------------------------------------- |
| `value` | `ModelSignal<any[]>` | Two-way bindable array of selected values using `[(value)]` |

Must be used with `<ng-template>` inside a popover element.
---

### Related components

Autocomplete uses [Listbox](/api/aria/listbox/Listbox) and [Option](/api/aria/listbox/Option) directives to render the suggestion list. See the [Listbox documentation](/guide/aria/listbox) for additional customization options.
Autocomplete uses standard standalone [Listbox](/api/aria/listbox/Listbox) and [Option](/api/aria/listbox/Option) directives. See the [Listbox documentation](/guide/aria/listbox) for advanced options.
Loading