igniteui-angular-sovn
Version:
Ignite UI for Angular is a dependency-free Angular toolkit for building modern web apps
198 lines (147 loc) • 9.66 kB
Markdown
# igxDropDown
**igxDropDown** displays a scrollable list of items which may be visually grouped and supports selection of a single item. Clicking or tapping an item selects it and closes the Drop Down.
A walkthrough of how to get started can be found [here](https://www.infragistics.com/products/ignite-ui-angular/angular/components/drop-down)
# Usage
## Drop downs are done by adding **igxDropDownListItems** to **igxDropDown** component
```html
<igx-drop-down>
<igx-drop-down-item *ngFor="let item of items"> {{ item.field }} </igx-drop-down-item>
</igx-drop-down>
```
To provide more useful visual information, use `isHeader` to group items semantically, or `disabled` to display an item as non-interactive.
```html
<igx-drop-down>
<igx-drop-down-item *ngFor="let item of items" disabled="{{item.disabled}}" isHeader="{{item.header}}"> {{ item.field }} </igx-drop-down-item>
</igx-drop-down>
```
## Grouping items
The **_igx-drop-down-item-group_** component can be used inside of the **_igx-drop-down_** to group **_igx-drop-down-items_**. The example below illustrates how to display hierarchical data in drop down groups:
```typescript
// in example.component.ts
export class MyExampleComponent {
...
foods: any[] = [{
name: 'Vegetables',
entries: [{
name: 'Cucumber',
refNo: `00000`
}, {
name: 'Lettuce',
refNo: `00001`
},
...
]
}, {
name: 'Fruits',
entries: [{
name: 'Banana',
refNo: `10000`
}, {
name: 'Tomato',
refNo: `10001`
},
...
]
}];
}
```
```html
<!-- in example.component.html -->
<igx-drop-down>
<igx-drop-down-item-group *ngFor="let foodGroup of foods" [label]="foodGroup.name">
<igx-drop-down-item *ngFor="let food of foodGroup.entries" [value]="food.refNo"> {{ food.name }} </igx-drop-down-item>
</igx-drop-down-item-group>
</igx-drop-down>
```
**_NOTE:_** The **_igx-drop-down-item-group_** tag can be used for grouping of **_igx-drop-down-item_** only an will forfeit any other content passed to it.
## Virtualized item list
The `igx-drop-down` supports the use of `IgxForOf` directive for displaying very large lists of data. To use a virtualized list of items in the drop-down, follow the steps below:
### Import IgxForOfModule
```typescript
import { ..., IgxForOfModule } from 'igniteui-angular-sovn';
...
@NgModule({
imports: [..., IgxForOfModule]
})
```
### Properly configure the template
Configure the drop-down to use `*igxFor` instead of `ngFor`. Some additional configuration must be passed:
- scrollOrientation - should be `'vertical'`
- containerSize - should be set to the height that the items container will have, as `number`. E.g. `public itemsMaxHeight = 480;`
- itemSize - should be set to the height of the **smallest** item that the list will have, as `number`. E.g. `public itemHeight = 32;`
```html
<igx-drop-down>
<div class="wrapping-div">
<igx-drop-down-item *igxFor="let item of localItems; index as index; scrollOrientation: 'vertical'; containerSize: itemsMaxHeight; itemSize: itemHeight;" [value]="item" [index]="index"> {{ item.data }} </igx-drop-down-item>
</div>
</igx-drop-down>
```
Furthermore, when using `*igxFor` in the drop-down template, items must have `value` and `index` bound. The `value` property should be unique for each item.
### Styling the container
In order for the drop-down list to properly display, the drop-down items must be wrapped in a container element (e.g. `<div>`).
The container element must have the following styles:
- `overflow: hidden;`
- `height` property set to the same as `itemsMaxHeight` in the template, in `px`. E.g. `height: 480px`
## Display Density
**igx-drop-down** supports setting of different display densities.
Display density is received through Angular's DI engine or can be set through the `[displayDensity]` input. The possilbe display densities are `compact`, `cosy` and `comfortable` (default).
Setting `[displayDensity]` affects the control's items' css properties, most notably heights, padding, font-size.
# API Summary
The following table summarizes some of the useful **igx-drop-down** component inputs, outputs and methods.
## Inputs
The following inputs are available in the **igx-drop-down** component:
| Name | Type | Description |
| :---------------- | :------ | :---------------------------------- |
| `width` | string | Sets the tab width of the control. |
| `height` | string | Sets the tab height of the control. |
| `maxHeight` | string | defines drop down maximum height |
| `allowItemsFocus` | boolean | Allows items to take focus. |
| `id` | string | Sets the drop down's id. |
<div class="divider--half"></div>
## Outputs
The following outputs are available in the **igx-drop-down** component:
| Name | Cancelable | Description | Parameters |
| :------------------ | :--------- | :----------------------------------------------------------------------- | :-------------------------------- |
| `selectionChanging` | false | Emitted when item selection is changing, before the selection completes. | `ISelectionEventArgs` |
| `opening` | true | Emitted before the dropdown is opened. | `IBaseCancelableBrowserEventArgs` |
| `opened` | false | Emitted when a dropdown is being opened. | `IBaseEventArgs` |
| `closing` | true | Emitted before the dropdown is closed. | `IBaseCancelableBrowserEventArgs` |
| `closed` | false | Emitted when a dropdown is being closed. | `IBaseEventArgs` |
**_NOTE:_** The using `*igxFor` to virtualize `igx-drop-down-item`s, `selectionChanging` will emit `newSeleciton` and `oldSelection` as type `{ value: any, index: number }`.
## Methods
The following methods are available in the **igx-drop-down** component:
| Signature | Description |
| :------------------------------- | :------------------------------------ |
| `toggle()` | Toggles the drop down opened/closed. |
| `setSelectedItem(index: number)` | Selects dropdown item by index. |
| `open()` | Opens the dropdown. |
| `close()` | Closes the dropdown. |
| `clearSelection()` | Deselects the selected dropdown item. |
## Getters
The following getters are available on the **igx-drop-down** component:
| Name | Type | Description |
| :---------------- | :--------------------------- | :---------------------------------------------------- |
| `selectedItem` | `any` | Gets the selected item. |
| `collapsed` | `boolean` | Gets if the drop down is collapsed. |
| `items` | `IgxDropDownItemComponent[]` | Gets all of the items but headers. |
| `headers` | `IgxDropDownItemComponent[]` | Gets header items. |
| `element` | `ElementRef` | Get dropdown html element. |
| `scrollContainer` | `ElementRef` | Get drop down's html element of its scroll container. |
**_NOTE:_** The using `*igxFor` to virtualize `igx-drop-down-item`s, `selectedItem` will return type `{ value: any, index: number }`, where `value` is the item's bound `value` property and `index` is the item's index property in the data set.
The following table summarizes some of the useful **igx-drop-down-item** component inputs, outputs and methods.
## Inputs
The following inputs are available in the **igx-drop-down-item** component:
| Name | Type | Description |
| :--------- | :------ | :------------------------------------------------------------------------------- |
| `selected` | boolean | Defines if the item is the selected item. Only one item can be selected at time. |
| `isHeader` | boolean | Defines if the item is a group header. |
| `disabled` | boolean | Disables the given item. |
| `index` | number | The data index of the drop down item. |
| `focused` | boolean | Defines if the given item is focused. |
| `value` | any | The value of the drop-down item. |
## Getters
The following getters are available on the **igx-drop-down-item** component:
| Name | Type | Description |
| :-------------- | :----------- | :------------------------ |
| `elementHeight` | `number` | Gets item element height. |
| `element` | `ElementRef` | Get item's html element. |