A select is used to choose an option from a provided list of items. Use the select for presenting options when your list is limited only. Think about a logical order of the items in your list according to their type.
The <dt-select>
is like the native <select>
a form control for selecting a
value from a list of options. It is also designed to work with Angular forms. By
using the <dt-option>
element, which is also provided in the select module,
you can add values to the select.
<dt-select placeholder="Choose your coffee" aria-label="Choose your coffee">
<dt-option value="ThePerfectPour">ThePerfectPour</dt-option>
<dt-option value="Affogato">Affogato</dt-option>
<dt-option value="Americano">Americano</dt-option>
<dt-option value="Bicerin">Bicerin</dt-option>
<dt-option value="Breve">Breve</dt-option>
<dt-option value="Café Bombón">Café Bombón</dt-option>
<dt-option value="Café au lait">Café au lait</dt-option>
<dt-option value="Caffé Corretto">Caffé Corretto</dt-option>
<dt-option value="Café Crema">Café Crema</dt-option>
<dt-option value="Caffé Latte">Caffé Latte</dt-option>
<dt-option value="Caffé macchiato">Caffé macchiato</dt-option>
<dt-option value="Café mélange">Café mélange</dt-option>
<dt-option value="Coffee milk">Coffee milk</dt-option>
<dt-option value="Cafe mocha">Cafe mocha</dt-option>
<dt-option value="Ca phe sua da">Ca phe sua da</dt-option>
<dt-option value="Kopi susu">Kopi susu</dt-option>
<dt-option value="Cappuccino ">Cappuccino</dt-option>
<dt-option value="Cappuccino-cups">Cappuccino-cups</dt-option>
<dt-option value="Cappuccino">Cappuccino</dt-option>
<dt-option value="Carajillo">Carajillo</dt-option>
<dt-option value="Cortado">Cortado</dt-option>
<dt-option value="Cuban espresso">Cuban espresso</dt-option>
<dt-option value="Espresso">Espresso</dt-option>
<dt-option value="The Flat White">The Flat White</dt-option>
<dt-option value="Frappuccino">Frappuccino</dt-option>
<dt-option value="Galao">Galao</dt-option>
<dt-option value="Greek frappé coffee">Greek frappé coffee</dt-option>
<dt-option value="Iced Coffee">Iced Coffee</dt-option>
<dt-option value="Indian filter coffee">Indian filter coffee</dt-option>
<dt-option value="Instant coffee">Instant coffee</dt-option>
<dt-option value="Irish coffee">Irish coffee</dt-option>
<dt-option value="Kopi Luwak">Kopi Luwak</dt-option>
<dt-option value="Kopi Tubruk">Kopi Tubruk</dt-option>
<dt-option value="Turkish coffee">Turkish coffee</dt-option>
<dt-option value="Vienna coffee">Vienna coffee</dt-option>
<dt-option value="Yuanyang">Yuanyang</dt-option>
</dt-select>
Imports
You have to import the DtSelectModule
when you want to use the <dt-select>
.
The <dt-select>
component also requires Angular's BrowserAnimationsModule
for animations. For more details on this see
Step 2: Animations in the
getting started guide.
@NgModule({
imports: [DtSelectModule],
})
class MyModule {}
Initialization
The API of the <dt-select>
is very similar to the native <select>
element,
but has some additional useful functions, like a placeholder property. It is
possible to disable the entire select or individual options in the select by
using the disabled property on the <dt-select>
or <dt-option>
The <dt-select>
also supports all of the form directives from the core
FormsModule (NgModel) and ReactiveFormsModule (FormControl, FormGroup, etc.) As
with native <select>
, <dt-select>
also supports a compareWith function.
(Additional information about using a custom compareWith function can be found
in the Angular forms documentation).
<p>
Selected Value:
<em>{{ selectedValue || 'No value selected' }}</em>
</p>
<dt-select
placeholder="Choose your coffee"
[(ngModel)]="selectedValue"
aria-label="Choose your coffee"
>
<dt-option *ngFor="let coffee of coffees" [value]="coffee.value">
{{ coffee.viewValue }}
</dt-option>
</dt-select>
DtSelect inputs
Name | Type | Description |
---|---|---|
placeholder |
string |
Placeholder to be shown if no value has been selected. |
required |
boolean |
Whether the component is required. |
compareWith |
(v1: T, v2: T) => boolean |
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. Defaults to value equality. |
value |
T |
Value of the select control. |
id |
string |
Unique id of the element. |
aria-label |
string |
Aria label of the select. If not specified, the placeholder will be used as label. |
aria-labelledby |
string |
Input that can be used to specify the aria-labelledby attribute. |
errorStateMatcher |
ErrorStateMatcher |
Object used to control when error messages are shown. |
panelClass |
string | string[] | Set<string> | { [key: string]: any } |
Classes to be passed to the select panel. Supports the same syntax as ngClass . |
DtSelect outputs
Name | Type | Description |
---|---|---|
openedChange |
EventEmitter<boolean> |
Event emitted when the select panel has been toggled. |
selectionChange |
EventEmitter<DtSelectChange<T>> |
Event emitted when the selected value has been changed by the user. |
valueChange |
EventEmitter<T> |
Event that emits whenever the raw value of the select changes. |
DtOption inputs
Name | Type | Description |
---|---|---|
value |
T |
The form value of the option. |
disabled |
boolean |
Whether the option is disabled. |
Getting and setting the select value The <dt-select>
supports 2-way binding to
the value property without the need for Angular forms.
<p>
Selected Value:
<em>{{ selectedValue || 'No value selected' }}</em>
</p>
<dt-select
placeholder="Choose your coffee"
[(value)]="selectedValue"
aria-label="Choose your coffee"
>
<dt-option value="ThePerfectPour">ThePerfectPour</dt-option>
<dt-option value="Affogato">Affogato</dt-option>
<dt-option value="Americano">Americano</dt-option>
</dt-select>
DtOption outputs
Name | Type | Description |
---|---|---|
selectionChange |
EventEmitter<DtOptionSelectionChange<T>> |
Event emitted when the option is selected or deselected. |
Creating groups of options
The <dt-optgroup>
element can be used to group common options under a
subheading. The name of the group can be set using the label property of
<dt-optgroup>
. Like individual <dt-option>
elements, an entire
<dt-optgroup>
can be disabled or enabled by setting the disabled property on
the group.
<dt-select placeholder="Select filter type" aria-label="Select filter type">
<dt-option value="Application">Application</dt-option>
<dt-option value="Bounce">Bounce</dt-option>
<dt-optgroup label="Browsers">
<dt-option value="Browser family">Browser family</dt-option>
<dt-option value="Browser type">Browser type</dt-option>
<dt-option value="Browser version">Browser version</dt-option>
</dt-optgroup>
<dt-optgroup label="Location">
<dt-option value="City">City</dt-option>
<dt-option value="Country">Country</dt-option>
<dt-option value="Continent">Continent</dt-option>
</dt-optgroup>
</dt-select>
Form field
The select component supports the <dt-form-field>
and all of its features.
These include error messages, hint text, prefix & suffix. For additional
information about these features, see the
form field documentation.
<dt-form-field>
<dt-label>Your Coffee:</dt-label>
<dt-select
placeholder="Choose your coffee"
required
[(ngModel)]="selectedValue"
>
<dt-option>No Coffee (Triggers an error)</dt-option>
<dt-option value="ThePerfectPour">ThePerfectPour</dt-option>
<dt-option value="Affogato">Affogato</dt-option>
<dt-option value="Americano">Americano</dt-option>
</dt-select>
<dt-hint>Choose one of the coffees in the list</dt-hint>
<dt-error>Please select a coffee</dt-error>
</dt-form-field>
Disabling the select or individual options
It is possible to disable the entire select or individual options in the select
by using the disabled property on the <dt-select>
and the <dt-option>
components respectively.
<dt-select
placeholder="Choose your coffee"
[disabled]="disabled"
aria-label="Choose your coffee"
>
<dt-option value="ThePerfectPour">ThePerfectPour</dt-option>
<dt-option disabled value="Affogato">Affogato</dt-option>
<dt-option value="Americano">Americano</dt-option>
</dt-select>
<p>
<dt-checkbox checked (change)="disabled = !disabled"> Disabled </dt-checkbox>
</p>
Non string values
The select component also supports non string, non basic value types.
<p>
Selected Value label:
<em>{{ selectedValue?.viewValue || 'No value selected' }}</em>
</p>
<dt-select
placeholder="Choose your coffee"
[(ngModel)]="selectedValue"
aria-label="Choose your coffee"
>
<dt-option *ngFor="let coffee of coffees" [value]="coffee">
{{ coffee.viewValue }}
</dt-option>
</dt-select>
Select with icons
It is possible to use icons to differentiate between the types of items in a select.
<!-- prettier-ignore -->
<dt-select placeholder="Choose a location" aria-label="Choose a location">
<dt-option value="Hagenberg">
<dt-icon class="dt-location-icon" name="hagenberg"></dt-icon>Hagenberg
</dt-option>
<dt-option value="Linz">
<dt-icon class="dt-location-icon" name="linz"></dt-icon>Linz
</dt-option>
<dt-option value="Klagenfurt">
<dt-icon class="dt-location-icon" name="klagenfurt"></dt-icon>Klagenfurt
</dt-option>
<dt-option value="Gdansk">
<dt-icon class="dt-location-icon" name="gdansk"></dt-icon>Gdansk
</dt-option>
<dt-option value="Graz">
<dt-icon class="dt-location-icon" name="graz"></dt-icon>Graz
</dt-option>
<dt-option value="Detroit">
<dt-icon class="dt-location-icon" name="detroit"></dt-icon>Detroit
</dt-option>
<dt-option value="Boston">
<dt-icon class="dt-location-icon" name="boston"></dt-icon>Boston
</dt-option>
</dt-select>
Custom trigger
It is possible to customize the trigger that is displayed when the select has a
value. By using the property <dt-select-value-template>
it's possible to
stablish a new template for the selected value.
<dt-select
placeholder="Choose your color"
[(ngModel)]="selectedValue"
aria-label="Choose your color"
>
<dt-select-value-template>
<span [style.background]="selectedValue?.value"></span>
</dt-select-value-template>
<dt-option *ngFor="let color of colors" [value]="color">
<div>
<span [style.background]="color.value"></span>
{{ color.viewValue }}
</div>
</dt-option>
</dt-select>
Accessibility
The select component without text or label should be given a meaningful label
via aria-label
or aria-labelledby
.
The select component has role="listbox"
and options inside select have
role="option"
.