Dropdown
About
What does it do?
- Navigation expands when user hovers or clicks on it revealing options to select.
When to use it?
- When there is limited space and you need to reduce the space taken on the page
- When an input is nonessential, e.g. sorting list
- When you need flexibility because you do not know how many options there will be. All options are contained within the drop down component.
When not to use it?
- Drop down creates more work for your user because it is a multi-step process, they hide available options and they slow users down by defaults therefore if possible use another component to display options e.g. radio buttons, text field, input selector
- Do not use when drop down option has more than 36 characters because users will not be able to read them on some mobile devices
HTML markup
<div class="wmnds-fe-group ">
<div class="wmnds-fe-dropdown">
<label class="wmnds-fe-label" for="dropdown-example">Form label</label>
<select class="wmnds-fe-dropdown__select " id="dropdown-example" name="dropdown-example">
<option value="" selected="true">Choose from list</option>
<option value="1">Option 1</option>
<option value="2">Option 2</option>
<option value="3">Option 3</option>
<option value="4">Option 4</option>
<option value="5">Option 5</option>
</select>
</div>
</div>
Nunjucks markup
{% from "wmnds/components/form-elements/dropdown/_dropdown.njk" import wmndsDropdown %}
{{
wmndsDropdown({
id: "dropdown-example",
name: "dropdown-example",
items: [
{
value: "",
contentText: "Choose from list",
selected: true,
disabled: false
},
{
value: "option1",
contentText: "Option 1",
selected: false,
disabled: false
},
{
value: "option2",
contentText: "Option 2",
selected: false,
disabled: false
},
{
value: "option3",
contentText: "Option 3",
selected: false,
disabled: false
}
],
describedBy: null,
label: "Dropdown label",
classes: null,
error: false,
errorMessage: {
id: null,
contentText: "Please select an option",
contentHTML: null,
classes: null
}
})
}}Nunjucks properties
| Name | Type | Description |
|---|---|---|
| id | string | Required. Id for each dropdown. |
| name | string | Required. Name property for the dropdown. |
| items | array | Required. Array of option items for the dropdown. See items below. |
| describedBy | string | One or more element IDs to add to the aria-describedby attribute, used to provide additional descriptive information for screenreader users. |
| label | string | Label text for the dropdown. |
| classes | string | Classes to add to the dropdown container. |
| error | boolean | If true, errorMessage will show. Defaults to false. |
| errorMessage | object | Options for the error message component. See errorMessage options below. |
Options for items
| Name | Type | Description |
|---|---|---|
| value | string | Value for the option item. |
| contentText | string | Required. Text for the option item. |
| selected | boolean | Sets the option as the selected. |
| disabled | boolean | Sets the option item as disabled. |
Options for errorMessage
| Name | Type | Description |
|---|---|---|
| id | string | Id attribute to add to the error message span tag. |
| contentText | string | Required. Text to use within the error message. If contentHTML is supplied, this is ignored. |
| contentHTML | string | Required. HTML to use within the error message |
| classes | string | Classes to add to the error message. |
Dropdown with error
HTML markup
<div class="wmnds-fe-group wmnds-fe-group--error">
<div class="wmnds-fe-dropdown">
<span class="wmnds-fe-error-message">Please select an option</span>
<label class="wmnds-fe-label" for="dropdown-error">Form label</label>
<select class="wmnds-fe-dropdown__select " id="dropdown-error" name="dropdown-example">
<option value="" selected="true">Choose from list</option>
<option value="1">Option 1</option>
<option value="2">Option 2</option>
<option value="3">Option 3</option>
<option value="4">Option 4</option>
<option value="5">Option 5</option>
</select>
</div>
</div>
Nunjucks markup
{% from "wmnds/components/form-elements/dropdown/_dropdown.njk" import wmndsDropdown %}
{{
wmndsDropdown({
id: "dropdown-example",
name: "dropdown-example",
items: [
{
value: "",
contentText: "Choose from list",
selected: true,
disabled: false
},
{
value: "option1",
contentText: "Option 1",
selected: false,
disabled: false
},
{
value: "option2",
contentText: "Option 2",
selected: false,
disabled: false
},
{
value: "option3",
contentText: "Option 3",
selected: false,
disabled: false
}
],
describedBy: null,
label: "Dropdown label",
classes: null,
error: false,
errorMessage: {
id: null,
contentText: "Please select an option",
contentHTML: null,
classes: null
}
})
}}Nunjucks properties
| Name | Type | Description |
|---|---|---|
| id | string | Required. Id for each dropdown. |
| name | string | Required. Name property for the dropdown. |
| items | array | Required. Array of option items for the dropdown. See items below. |
| describedBy | string | One or more element IDs to add to the aria-describedby attribute, used to provide additional descriptive information for screenreader users. |
| label | string | Label text for the dropdown. |
| classes | string | Classes to add to the dropdown container. |
| error | boolean | If true, errorMessage will show. Defaults to false. |
| errorMessage | object | Options for the error message component. See errorMessage options below. |
Options for items
| Name | Type | Description |
|---|---|---|
| value | string | Value for the option item. |
| contentText | string | Required. Text for the option item. |
| selected | boolean | Sets the option as the selected. |
| disabled | boolean | Sets the option item as disabled. |
Options for errorMessage
| Name | Type | Description |
|---|---|---|
| id | string | Id attribute to add to the error message span tag. |
| contentText | string | Required. Text to use within the error message. If contentHTML is supplied, this is ignored. |
| contentHTML | string | Required. HTML to use within the error message |
| classes | string | Classes to add to the error message. |