To create a dropdown web component use the <dk-dropdown> element as the container and add your options with the <dk-option> element as needed.
<dk-dropdown id="dropdownId"">
<dk-option value="01">Option 1</dk-option>
<dk-option value="02">Option 2</dk-option>
<dk-option value="03">Option 3</dk-option>
</dk-dropdown>
Controlling the Values
The easiest way to control the value of the dropdown is to set a string that matches the value of the option that you want selected.
document.querySelector("#dropdownId").value = "02";
For a multiple select dropdown the value is stored as an array of values that matched the selected options.
document.querySelector("#dropdownId").value = ["01", "03"];
Width
The dropdown will default to a width that is wide enough to fit the option with longest label text.
You can override this by supplying a width style directly to the dk-dropdown or by adding a classname which will control the width.
#dropdownId {width:250px}
Listening to Change
The dropdown will emit a custom event called dkChange. This event will contain the newly selected value under the detail of the event.
const dropdown = document.querySelector("#dropdownId");
dropdown.addEventListener("dkChange", (e) => {
const newValue = e.detail.value;
});
React
When using the dropdown in react it is best practice to use the @digit/react package that can be installed with npm inside the DK firewall.
This package will give you react wrapped versions of the Digit web components.
This is the best way to capture the dkChange event that is emitted when a user selects a new value.
This is required to keep the react state updated with the internal state of the dropdown.
import { useState } from "react";
import { DkDropdown, DkOption, DkButton } from "@digit/react";
function YourComponent() {
const [value, setValue] = useState(null);
return (
<>
<DkButton onClick={() => setValue(null)}>
{value || "No value selected"}
</DkButton>
<DkDropdown
placeholder="Placeholder Text"
value={value}
onDkChange={(e) => setValue(e.detail.value)}
>
{optionArray.map((o) => (
<DkOption key={o.value} value={o.value} label={o.label} />
))}
</DkDropdown>
</>
);
}
Properties
Use properties and attributes to control the web component as well as pass required data to it. Some properties won't have an attribute name, this is because to use that property you can't use it as an html attribute it must be set using javascript as a property of the element.
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
disabled | disabled | Disables dropdown | boolean | false |
enableFilter | filter | Provide a text input to filter options | boolean | null |
error | error | Enables the error styles for the dropdown | boolean | false |
filterPlaceholder | filter-placeholder | Set the text of the filter placeholder | string | "Type to search..." |
isOpen | open | Controls the open state of the dropdown | boolean | false |
multiple | multiple | Allows for multiple options to be selected | boolean | false |
placeholder | placeholder | Text to show if no option is selected | string | "Make a Selection..." |
selected | undefined | IOption[] | string[] | null | |
value | value | Value of selected option. Use this prop to externally control what option is selected. Note: If you are externally controlling it make sure to add a listener for dkChange otherwise your state will be out of sync. | string | string[] | null |
Events
| Event | Description | Type |
|---|---|---|
dkChange | The event that is fired whenever the value of dropdown changes. The label, and value of the selected option gets passed with the event. | { value: DropdownValue; } |
Dropdown
Standard dropdown is created using the <dk-dropdown> element and adding <dk-option value="Option Value"> elements for each select option.
<dk-dropdown>
<dk-option value=""></dk-option>
<dk-option value="AB">Alberta</dk-option>
<dk-option value="BC">
British Columbia
</dk-option>
<dk-option value="MB">Manitoba</dk-option>
<dk-option value="NB">
New Brunswick
</dk-option>
<dk-option value="NS">
Nova Scotia
</dk-option>
<dk-option value="NT">
Northwest Territories
</dk-option>
<dk-option value="NU">Nunavut</dk-option>
<dk-option value="ON">Ontario</dk-option>
<dk-option value="PE">
Prince Edward Island
</dk-option>
<dk-option value="QC">Quebec</dk-option>
<dk-option value="SK">
Saskatchewan
</dk-option>
</dk-dropdown>Preset Value
To set a default selected value to the dropdown add the value="Selected Value" attribute.
<dk-dropdown>
<dk-option value=""></dk-option>
<dk-option value="AB">Alberta</dk-option>
<dk-option value="BC">
British Columbia
</dk-option>
<dk-option value="MB">Manitoba</dk-option>
<dk-option value="NB">
New Brunswick
</dk-option>
<dk-option value="NS">
Nova Scotia
</dk-option>
<dk-option value="NT">
Northwest Territories
</dk-option>
<dk-option value="NU">Nunavut</dk-option>
<dk-option value="ON">Ontario</dk-option>
<dk-option value="PE">
Prince Edward Island
</dk-option>
<dk-option value="QC">Quebec</dk-option>
<dk-option value="SK">
Saskatchewan
</dk-option>
</dk-dropdown>Placeholder
To display custom text as the placeholder add the placeholder="Custom Placeholder Text" attribute.
<dk-dropdown placeholder="Custom Placeholder Text">
<dk-option value=""></dk-option>
<dk-option value="AB">Alberta</dk-option>
<dk-option value="BC">
British Columbia
</dk-option>
<dk-option value="MB">Manitoba</dk-option>
<dk-option value="NB">
New Brunswick
</dk-option>
<dk-option value="NS">
Nova Scotia
</dk-option>
<dk-option value="NT">
Northwest Territories
</dk-option>
<dk-option value="NU">Nunavut</dk-option>
<dk-option value="ON">Ontario</dk-option>
<dk-option value="PE">
Prince Edward Island
</dk-option>
<dk-option value="QC">Quebec</dk-option>
<dk-option value="SK">
Saskatchewan
</dk-option>
</dk-dropdown>Auto Filter
When you pass more than 12 options to a dropdown it will automatically enable the filter. To enable the filter on smaller dropdowns add the filter="true" attribute.
<dk-dropdown>
<dk-option value="AL">Alabama</dk-option>
<dk-option value="AK">Alaska</dk-option>
<dk-option value="AZ">Arizona</dk-option>
<dk-option value="AR">Arkansas</dk-option>
<dk-option value="CA">
California
</dk-option>
<dk-option value="CO">Colorado</dk-option>
<dk-option value="CT">
Connecticut
</dk-option>
<dk-option value="DE">Delaware</dk-option>
<dk-option value="DC">
District Of Columbia
</dk-option>
<dk-option value="FL">Florida</dk-option>
<dk-option value="GA">Georgia</dk-option>
<dk-option value="HI">Hawaii</dk-option>
<dk-option value="ID">Idaho</dk-option>
<dk-option value="IL">Illinois</dk-option>
<dk-option value="IN">Indiana</dk-option>
<dk-option value="IA">Iowa</dk-option>
<dk-option value="KS">Kansas</dk-option>
<dk-option value="KY">Kentucky</dk-option>
<dk-option value="LA">
Louisiana
</dk-option>
<dk-option value="ME">Maine</dk-option>
<dk-option value="MD">Maryland</dk-option>
<dk-option value="MA">
Massachusetts
</dk-option>
<dk-option value="MI">Michigan</dk-option>
<dk-option value="MN">
Minnesota
</dk-option>
<dk-option value="MS">
Mississippi
</dk-option>
<dk-option value="MO">Missouri</dk-option>
<dk-option value="MT">Montana</dk-option>
<dk-option value="NE">Nebraska</dk-option>
<dk-option value="NV">Nevada</dk-option>
<dk-option value="NH">
New Hampshire
</dk-option>
<dk-option value="NJ">
New Jersey
</dk-option>
<dk-option value="NM">
New Mexico
</dk-option>
<dk-option value="NY">New York</dk-option>
<dk-option value="NC">
North Carolina
</dk-option>
<dk-option value="ND">
North Dakota
</dk-option>
<dk-option value="OH">Ohio</dk-option>
<dk-option value="OK">Oklahoma</dk-option>
<dk-option value="OR">Oregon</dk-option>
<dk-option value="PA">
Pennsylvania
</dk-option>
<dk-option value="RI">
Rhode Island
</dk-option>
<dk-option value="SC">
South Carolina
</dk-option>
<dk-option value="SD">
South Dakota
</dk-option>
<dk-option value="TN">
Tennessee
</dk-option>
<dk-option value="TX">Texas</dk-option>
<dk-option value="UT">Utah</dk-option>
<dk-option value="VT">Vermont</dk-option>
<dk-option value="VA">Virginia</dk-option>
<dk-option value="WA">
Washington
</dk-option>
<dk-option value="WV">
West Virginia
</dk-option>
<dk-option value="WI">
Wisconsin
</dk-option>
<dk-option value="WY">Wyoming</dk-option>
</dk-dropdown>Filter Placeholder
To display custom text in the filter input field add the filter-placeholder="Custom Filter Placeholder Text" attribute
<dk-dropdown filter-placeholder="Custom Filter Placeholder">
<dk-option value="AL">Alabama</dk-option>
<dk-option value="AK">Alaska</dk-option>
<dk-option value="AZ">Arizona</dk-option>
<dk-option value="AR">Arkansas</dk-option>
<dk-option value="CA">
California
</dk-option>
<dk-option value="CO">Colorado</dk-option>
<dk-option value="CT">
Connecticut
</dk-option>
<dk-option value="DE">Delaware</dk-option>
<dk-option value="DC">
District Of Columbia
</dk-option>
<dk-option value="FL">Florida</dk-option>
<dk-option value="GA">Georgia</dk-option>
<dk-option value="HI">Hawaii</dk-option>
<dk-option value="ID">Idaho</dk-option>
<dk-option value="IL">Illinois</dk-option>
<dk-option value="IN">Indiana</dk-option>
<dk-option value="IA">Iowa</dk-option>
<dk-option value="KS">Kansas</dk-option>
<dk-option value="KY">Kentucky</dk-option>
<dk-option value="LA">
Louisiana
</dk-option>
<dk-option value="ME">Maine</dk-option>
<dk-option value="MD">Maryland</dk-option>
<dk-option value="MA">
Massachusetts
</dk-option>
<dk-option value="MI">Michigan</dk-option>
<dk-option value="MN">
Minnesota
</dk-option>
<dk-option value="MS">
Mississippi
</dk-option>
<dk-option value="MO">Missouri</dk-option>
<dk-option value="MT">Montana</dk-option>
<dk-option value="NE">Nebraska</dk-option>
<dk-option value="NV">Nevada</dk-option>
<dk-option value="NH">
New Hampshire
</dk-option>
<dk-option value="NJ">
New Jersey
</dk-option>
<dk-option value="NM">
New Mexico
</dk-option>
<dk-option value="NY">New York</dk-option>
<dk-option value="NC">
North Carolina
</dk-option>
<dk-option value="ND">
North Dakota
</dk-option>
<dk-option value="OH">Ohio</dk-option>
<dk-option value="OK">Oklahoma</dk-option>
<dk-option value="OR">Oregon</dk-option>
<dk-option value="PA">
Pennsylvania
</dk-option>
<dk-option value="RI">
Rhode Island
</dk-option>
<dk-option value="SC">
South Carolina
</dk-option>
<dk-option value="SD">
South Dakota
</dk-option>
<dk-option value="TN">
Tennessee
</dk-option>
<dk-option value="TX">Texas</dk-option>
<dk-option value="UT">Utah</dk-option>
<dk-option value="VT">Vermont</dk-option>
<dk-option value="VA">Virginia</dk-option>
<dk-option value="WA">
Washington
</dk-option>
<dk-option value="WV">
West Virginia
</dk-option>
<dk-option value="WI">
Wisconsin
</dk-option>
<dk-option value="WY">Wyoming</dk-option>
</dk-dropdown>Error
To utilize the default red error styles on the dropdown add the error="true" attribute.
<dk-dropdown error="true">
<dk-option value="AL">Alabama</dk-option>
<dk-option value="AK">Alaska</dk-option>
<dk-option value="AZ">Arizona</dk-option>
<dk-option value="AR">Arkansas</dk-option>
<dk-option value="CA">
California
</dk-option>
<dk-option value="CO">Colorado</dk-option>
<dk-option value="CT">
Connecticut
</dk-option>
<dk-option value="DE">Delaware</dk-option>
<dk-option value="DC">
District Of Columbia
</dk-option>
<dk-option value="FL">Florida</dk-option>
<dk-option value="GA">Georgia</dk-option>
<dk-option value="HI">Hawaii</dk-option>
<dk-option value="ID">Idaho</dk-option>
<dk-option value="IL">Illinois</dk-option>
<dk-option value="IN">Indiana</dk-option>
<dk-option value="IA">Iowa</dk-option>
<dk-option value="KS">Kansas</dk-option>
<dk-option value="KY">Kentucky</dk-option>
<dk-option value="LA">
Louisiana
</dk-option>
<dk-option value="ME">Maine</dk-option>
<dk-option value="MD">Maryland</dk-option>
<dk-option value="MA">
Massachusetts
</dk-option>
<dk-option value="MI">Michigan</dk-option>
<dk-option value="MN">
Minnesota
</dk-option>
<dk-option value="MS">
Mississippi
</dk-option>
<dk-option value="MO">Missouri</dk-option>
<dk-option value="MT">Montana</dk-option>
<dk-option value="NE">Nebraska</dk-option>
<dk-option value="NV">Nevada</dk-option>
<dk-option value="NH">
New Hampshire
</dk-option>
<dk-option value="NJ">
New Jersey
</dk-option>
<dk-option value="NM">
New Mexico
</dk-option>
<dk-option value="NY">New York</dk-option>
<dk-option value="NC">
North Carolina
</dk-option>
<dk-option value="ND">
North Dakota
</dk-option>
<dk-option value="OH">Ohio</dk-option>
<dk-option value="OK">Oklahoma</dk-option>
<dk-option value="OR">Oregon</dk-option>
<dk-option value="PA">
Pennsylvania
</dk-option>
<dk-option value="RI">
Rhode Island
</dk-option>
<dk-option value="SC">
South Carolina
</dk-option>
<dk-option value="SD">
South Dakota
</dk-option>
<dk-option value="TN">
Tennessee
</dk-option>
<dk-option value="TX">Texas</dk-option>
<dk-option value="UT">Utah</dk-option>
<dk-option value="VT">Vermont</dk-option>
<dk-option value="VA">Virginia</dk-option>
<dk-option value="WA">
Washington
</dk-option>
<dk-option value="WV">
West Virginia
</dk-option>
<dk-option value="WI">
Wisconsin
</dk-option>
<dk-option value="WY">Wyoming</dk-option>
</dk-dropdown>Disabled
To set the dropdown to be disabled add the disabled="true" attribute.
<dk-dropdown disabled="true">
<dk-option value="AL">Alabama</dk-option>
<dk-option value="AK">Alaska</dk-option>
<dk-option value="AZ">Arizona</dk-option>
<dk-option value="AR">Arkansas</dk-option>
<dk-option value="CA">
California
</dk-option>
<dk-option value="CO">Colorado</dk-option>
<dk-option value="CT">
Connecticut
</dk-option>
<dk-option value="DE">Delaware</dk-option>
<dk-option value="DC">
District Of Columbia
</dk-option>
<dk-option value="FL">Florida</dk-option>
<dk-option value="GA">Georgia</dk-option>
<dk-option value="HI">Hawaii</dk-option>
<dk-option value="ID">Idaho</dk-option>
<dk-option value="IL">Illinois</dk-option>
<dk-option value="IN">Indiana</dk-option>
<dk-option value="IA">Iowa</dk-option>
<dk-option value="KS">Kansas</dk-option>
<dk-option value="KY">Kentucky</dk-option>
<dk-option value="LA">
Louisiana
</dk-option>
<dk-option value="ME">Maine</dk-option>
<dk-option value="MD">Maryland</dk-option>
<dk-option value="MA">
Massachusetts
</dk-option>
<dk-option value="MI">Michigan</dk-option>
<dk-option value="MN">
Minnesota
</dk-option>
<dk-option value="MS">
Mississippi
</dk-option>
<dk-option value="MO">Missouri</dk-option>
<dk-option value="MT">Montana</dk-option>
<dk-option value="NE">Nebraska</dk-option>
<dk-option value="NV">Nevada</dk-option>
<dk-option value="NH">
New Hampshire
</dk-option>
<dk-option value="NJ">
New Jersey
</dk-option>
<dk-option value="NM">
New Mexico
</dk-option>
<dk-option value="NY">New York</dk-option>
<dk-option value="NC">
North Carolina
</dk-option>
<dk-option value="ND">
North Dakota
</dk-option>
<dk-option value="OH">Ohio</dk-option>
<dk-option value="OK">Oklahoma</dk-option>
<dk-option value="OR">Oregon</dk-option>
<dk-option value="PA">
Pennsylvania
</dk-option>
<dk-option value="RI">
Rhode Island
</dk-option>
<dk-option value="SC">
South Carolina
</dk-option>
<dk-option value="SD">
South Dakota
</dk-option>
<dk-option value="TN">
Tennessee
</dk-option>
<dk-option value="TX">Texas</dk-option>
<dk-option value="UT">Utah</dk-option>
<dk-option value="VT">Vermont</dk-option>
<dk-option value="VA">Virginia</dk-option>
<dk-option value="WA">
Washington
</dk-option>
<dk-option value="WV">
West Virginia
</dk-option>
<dk-option value="WI">
Wisconsin
</dk-option>
<dk-option value="WY">Wyoming</dk-option>
</dk-dropdown>Multi Select
To allow for multiple options to be selexted add the multiple="true" attribute.
<dk-dropdown multiple="true">
<dk-option value="AL">Alabama</dk-option>
<dk-option value="AK">Alaska</dk-option>
<dk-option value="AZ">Arizona</dk-option>
<dk-option value="AR">Arkansas</dk-option>
<dk-option value="CA">
California
</dk-option>
<dk-option value="CO">Colorado</dk-option>
<dk-option value="CT">
Connecticut
</dk-option>
<dk-option value="DE">Delaware</dk-option>
<dk-option value="DC">
District Of Columbia
</dk-option>
<dk-option value="FL">Florida</dk-option>
<dk-option value="GA">Georgia</dk-option>
<dk-option value="HI">Hawaii</dk-option>
<dk-option value="ID">Idaho</dk-option>
<dk-option value="IL">Illinois</dk-option>
<dk-option value="IN">Indiana</dk-option>
<dk-option value="IA">Iowa</dk-option>
<dk-option value="KS">Kansas</dk-option>
<dk-option value="KY">Kentucky</dk-option>
<dk-option value="LA">
Louisiana
</dk-option>
<dk-option value="ME">Maine</dk-option>
<dk-option value="MD">Maryland</dk-option>
<dk-option value="MA">
Massachusetts
</dk-option>
<dk-option value="MI">Michigan</dk-option>
<dk-option value="MN">
Minnesota
</dk-option>
<dk-option value="MS">
Mississippi
</dk-option>
<dk-option value="MO">Missouri</dk-option>
<dk-option value="MT">Montana</dk-option>
<dk-option value="NE">Nebraska</dk-option>
<dk-option value="NV">Nevada</dk-option>
<dk-option value="NH">
New Hampshire
</dk-option>
<dk-option value="NJ">
New Jersey
</dk-option>
<dk-option value="NM">
New Mexico
</dk-option>
<dk-option value="NY">New York</dk-option>
<dk-option value="NC">
North Carolina
</dk-option>
<dk-option value="ND">
North Dakota
</dk-option>
<dk-option value="OH">Ohio</dk-option>
<dk-option value="OK">Oklahoma</dk-option>
<dk-option value="OR">Oregon</dk-option>
<dk-option value="PA">
Pennsylvania
</dk-option>
<dk-option value="RI">
Rhode Island
</dk-option>
<dk-option value="SC">
South Carolina
</dk-option>
<dk-option value="SD">
South Dakota
</dk-option>
<dk-option value="TN">
Tennessee
</dk-option>
<dk-option value="TX">Texas</dk-option>
<dk-option value="UT">Utah</dk-option>
<dk-option value="VT">Vermont</dk-option>
<dk-option value="VA">Virginia</dk-option>
<dk-option value="WA">
Washington
</dk-option>
<dk-option value="WV">
West Virginia
</dk-option>
<dk-option value="WI">
Wisconsin
</dk-option>
<dk-option value="WY">Wyoming</dk-option>
</dk-dropdown>