Select lets users choose one or multiple values from a known dropdown list. Use it in one ngs-form-field for forms, filters, settings, table filters, and admin configuration fields when the available options are predefined.
Use ngs-select with ngs-option for each option and ngs-optgroup when options need visible grouping. Select supports placeholder, required and disabled states, single and multiple selection, Angular forms, value, selectionChange, custom trigger content, and optional header, body, and footer slots for richer dropdown panels.
Do not use Select as a command menu, action list, route navigation, compact mode switch, simple visible radio group, rich card choice, or free text search input. Use Menu, Navigation, Tabs, Segmented, Radio, RadioCard, or Autocomplete when those match the job better. Use dedicated selectors such as CountrySelect, CurrencySelect, DateFormatSelect, or TimezoneSelect when the domain already has its own component.
Select API
Clearable usage
<ngs-select clearable [formControl]="status">
<ngs-option value="active">Active</ngs-option>
<ngs-option value="pending">Pending</ngs-option>
</ngs-select>
Inputs
| Name | Description |
|---|
id | Unique identifier for the select component. |
placeholder | Placeholder text to display when no value is selected. |
disabled | Whether the select is disabled. |
required | Whether the select is required. |
multiple | Whether the user can select multiple options. |
hideCheckIcon | Whether to hide the check icon for selected options. |
clearable | Whether to show a clear button next to the arrow when a value is selected. Clearing emits selectionChange and writes null for single select or an empty array for multiple select. |
dataSource | Async option source for server-backed select values. Receives paging, search, selected values, request reason, and an optional abort signal. |
pageSize | Number of async options requested per page. Defaults to 25. |
searchable | Shows the async search input in the panel. Search requests are sent to dataSource. |
searchDebounce | Debounce in milliseconds before sending a search request. Defaults to 250. |
minSearchLength | Minimum number of typed characters before remote search runs. Defaults to 0. |
loadOnOpen | Loads async options when the select panel opens. Defaults to true. |
ariaLabel | Aria-label for the select. |
tabIndex | TabIndex for the select. |
aria-describedby | Aria-describedby for the select. |
Async data source
Use dataSource when options come from an API. The function must return the selected option during the first request when selectedValues contains the current form value, so the trigger can render the selected label before the option page is opened.
import { SelectDataSource } from '@ngstarter-ui/components/select';
readonly usersDataSource: SelectDataSource<User> = async request => {
const response = await usersApi.search({
search: request.search,
page: request.page,
pageSize: request.pageSize,
selectedValues: request.selectedValues,
});
return {
items: response.users.map(user => ({
label: user.name,
value: user.id,
data: user,
})),
hasMore: response.hasMore,
nextCursor: response.nextPage,
};
};
<ngs-select
[formControl]="owner"
[dataSource]="usersDataSource"
[pageSize]="20"
searchable
[minSearchLength]="1">
</ngs-select>
SelectDataSourceRequest
| Name | Description |
|---|
search | Current search text. Empty for initial and open requests. |
page | One-based page number requested by the select. |
pageSize | Configured page size passed from the select. |
selectedValues | Current selected value or values. Return matching options on the first request. |
reason | Why the request was made: initial, open, search, or page. |
signal | Optional abort signal for cancelling stale remote requests. |
Async templates
Use ngsOptionContentDef to customize async option rows and ngsSelectValueDef to customize the selected value display. Both templates receive the option data payload.
<ng-template ngsOptionContentDef let-user let-label="label">
<strong>{{ user.name }}</strong>
<span>{{ user.team }}</span>
</ng-template>
<ng-template ngsSelectValueDef let-user let-label="label">
{{ user?.name || label }}
</ng-template>
Outputs
| Name | Description |
|---|
selectionChange | Event emitted when the selected value changes. |
opened | Event emitted when the select panel is opened. |
closed | Event emitted when the select panel is closed. |
Public Properties
| Name | Description |
|---|
hasValue | Computed signal that returns true when the select currently has a selected value. It is false for null, undefined, an empty string, or an empty array. |
ngs-option Inputs
| Name | Description |
|---|
value | Value written to the parent select control when this option is selected. |
data | Optional full option payload, such as an object or typed status. The select value still uses value, while filter trigger custom value templates receive data for rendering richer selected values. |
disabled | Whether the option is disabled. |
selected | Whether the option starts selected. |