--- title: Dropdowns - Done slug: dropdowns-done createdAt: 2025-02-20T22:50:23.691Z --- # Normal Dropdown (Forms) The "normal" dropdown is a select replacement. ## Dependencies - Requires dropdowns.js ## Notes **ONLY APPLIES to Dropdowns with .dropdown class: **If i have provided code in the past with BOTH .dropdown and webflow classes (w-dropdown, w-dropdown-toggle, w-dropdown-list, the webflow classes should be removed. We should only be depending on dropdown.js for normal dropdowns.) ## How it Works The dropdown operates in four main phases: 1. **Initialization** - **DOM Ready:** When the DOM is fully loaded, the script selects all elements with the `.dropdown` class. - **Storing Original Placeholder:** For each dropdown, the original text in the `.dropdown-text` element is saved to a custom data attribute (`data-original-placeholder`) for later use. - **Preselection Check:** The script looks for an option with `data-dropdown-selected="true"`. - If found, it updates the dropdown’s `data-value` and displays the corresponding option text, while marking the option’s icon as selected. - If not found (and if `data-value` is empty), it applies the `dropdown-placeholder` class to `.dropdown-text`. - **Closing on Load:** Each dropdown is explicitly closed, ensuring the `.dropdown-open` container is hidden. 2. **Toggling the Dropdown** - **Click on Closed Section:** Clicking the `.dropdown-closed` element toggles the dropdown’s open/closed state. - **Single Open Dropdown:** If another dropdown is open, it is closed before the clicked dropdown is toggled. - **Displaying Options:** Opening the dropdown sets the `.dropdown-open` container to display (e.g., `display: block`). 3. **Option Selection** - **Click on an Option:** When a `.dropdown-option` is clicked, the script: - Prevents the default action and stops the event from propagating. - **Clear Selection Option:** If the clicked option has the `data-dropdown-clear-selection` attribute: - Clears any existing selections in the dropdown. - Resets `data-value` to an empty string. - Restores the original placeholder text from `data-original-placeholder` and applies the `dropdown-placeholder` class. - **Normal Option Selection:** Otherwise, for a regular option: - All other options have their selection state cleared (removing `data-dropdown-selected` and the `.selected` class from icons). - The clicked option is marked as selected by setting `data-dropdown-selected="true"` and adding the `.selected` class to its icon. - The dropdown’s `data-value` is updated with the option’s value. - The visible text in `.dropdown-text` is updated to show the selected option, and the `dropdown-placeholder` class is removed. - **Closing After Selection:** After updating the selection, the dropdown is closed by hiding the `.dropdown-open` container. 4. **Click-Away Handling** - **Global Listener:** A document-level click listener ensures that if the user clicks anywhere outside an open dropdown, any open dropdown will be closed automatically. This design ensures a self-contained, reusable dropdown component using only vanilla JavaScript and the custom classes provided. ## Dropdown Filter (optional) **Requires dropdown-filter.js** This optional component goes at the top of the dropdown field. It allows the user to enter text to filter the dropdown options. dropdown-filter.js includes required JS for this functionality. ## Attributes / Settings ### Dropdown Container (`

`) | Attribute/Class | Description | Example/Note | | --------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | `class="dropdown"` | Main container for the dropdown component. | `

`) | Attribute/Class | Description | Example/Note | | ------------------------- | -------------------------------------------------------------------------------- | ------------------------------- | | `class="dropdown-closed"` | Visible part of the dropdown that the user clicks to open or close the dropdown. | `

` | ### Dropdown Closed Table Styling (`

`) | Attribute/Class | Description | Example/Note | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | `.table-filter` | Optional class applied to the dropdown’s closed section (`.dropdown-closed`) to style it for table filter rows or pagination filters. | `

` | ### Dropdown Text (`

`) | Attribute/Class | Description | Example/Note | | ----------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | `class="dropdown-text"` | Displays the selected option's text, or a placeholder if no option is selected. | `` | | `dropdown-placeholder` | CSS class applied to the text element when no option is selected (i.e. when `data-value` is empty). | Added automatically if no selection is made | ### Dropdown Open Section (`

`) | Attribute/Class | Description | Example/Note | | ----------------------- | -------------------------------------------------------------------------------------- | ----------------------------- | | `class="dropdown-open"` | Container for the list of options. Hidden by default; shown when the dropdown is open. | `

`) | Attribute/Class | Description | Example/Note | | ------------------------------ | ------------------------------------------------------ | -------------------------------------------------- | | `class="dropdown-option-text"` | Contains the text displayed for the individual option. | `` | ### Dropdown Option Selected Icon (`

`) | Attribute/Class | Description | Example/Note | | --------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | `class="dropdown-option-selected-icon"` | Holds the icon that indicates the option's selection state. Receives the `.selected` class when selected. | `` | | `.selected` | CSS class applied to indicate that this option is selected. | Added dynamically when the option is selected | ### Dropdown Filter (Optional) | Attribute/Class | Description | Example/Note | | ------------------------- | --------------------------------------------------- | ---------------------------------------- | | `class="dropdown-filter"` | Container for the optional dropdown filter element. | `` | ### Dropdown Filter Input | Attribute/Class | Description | Example/Note | | ------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `class="dropdown-filter-input"` | The input field used to filter the dropdown options. | `` | | `maxlength="256"` | Limits the number of characters in the input field. | `maxlength="256"` | | `placeholder="Filter"` | Text displayed as a hint when the input is empty. | `placeholder="Filter"` | | `type="text"` | Specifies that the input is of type text. | `type="text"` | ### Dropdown Open Direction Modifiers | Modifier Class | Description | Example/Note | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | | `left` | Adjusts the positioning of the open dropdown (`.dropdown-open`) so that it aligns to the left side of the closed element rather than expanding to the right. | Use as a class on `.dropdown-open` when you need the dropdown to open leftward (e.g., near the right edge). | | `top` | Positions the dropdown open container above the closed element. | Apply as `.dropdown-open.top` to have the dropdown open upward. | | `top-left` | Combines top and left positioning, placing the dropdown open container above and aligned to the left of the closed element. | Use as `.dropdown-open.top-left` for combined upward and leftward alignment. | *Default Behavior:* By default, `.dropdown-open` opens downward with `left: 0` and `top: 0`, expanding naturally to the right if its content exceeds the width of the closed element. ### Dropdown Open Max-Width Modifiers | Modifier Class | Description | Example/Note | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `.max-100` | Restricts the maximum width of the dropdown open container to a specific size (e.g., 100px). Useful when you want to constrain the width for design consistency. | Apply as an additional class on `.dropdown-open` (e.g., `