Dropdown

A dropdown component that can be used for simple stylized selects, more complex ones with simple fuzzy text search, or async dropdowns that get their data from rest or admin ajax.

Parameters:
NameTypeDescription
optionsobject

The options for the component.

Properties
NameTypeDescription
autoPositionboolean

Whether or not to auto position the dropdown above or below based on available room.

attributesstring

The attributes to add to the wrapper element, space seperated.

baseUrlstring

The base url for the request if async.

closeOnSelectboolean

Whether or not to close the dropdown when an item is selected.

containerstring

The container to append the dropdown to.

detectTitleLengthboolean

Whether or not to detect the length of the title and adjust the width of the dropdown.

dropdownListAttributesstring

The attributes to add to the dropdown list element.

endpointsobject

The endpoints for the request if async.

endpointArgsobject

The arguments for the request if async.

endpointKeystring

The key for the endpoint if async.

endpointRequestOptionsobject

The request options for the request if async.

endpointUseRestboolean

Whether or not to use the rest api for the request if async.

hasSearchboolean

Whether or not to show the search input.

insertPositionstring

The position to insert the dropdown in the dom.

listDataArray

The list data for the dropdown.

onItemSelectfunction

The callback function to run when an item is selected.

onOpenfunction

The callback function to run when the dropdown is opened.

onClosefunction

The callback function to run when the dropdown is closed.

renderboolean

Whether or not to render the dropdown.

renderListDataboolean

Whether or not to render the list data.

renderTargetstring

The target to render the dropdown to.

revealstring

The reveal type for the dropdown.

searchAriaTextstring

The aria text for the search input.

searchInputIdstring

The id for the search input.

searchPlaceholderstring

The placeholder for the search input.

searchTypestring

Basic or async. async requires endpoint config and key, plus baseUrl

selectorstring

The selector for the dropdown.

showSpinnerboolean

Whether or not to show the spinner when searching for results or page is reloading.

swapLabelboolean

Whether or not to swap the label and value on select of an item.

titleLengthThresholdMediumnumber

The threshold for the medium title length.

titleLengthThresholdLongnumber

The threshold for the long title length.

triggerAriaIdstring

The id for the trigger aria.

triggerAriaTextstring

The aria text for the trigger.

triggerClassesstring

The classes for the trigger.

triggerIdstring

The id for the trigger.

triggerPlaceholderstring

The placeholder for the trigger.

triggerSelectedstring

The selected item for the trigger.

triggerTitlestring

The title for the trigger.

wrapperClassesstring

The classes for the wrapper, space seperated string.

Since
  • 1.1.16
Source
Returns:

The class instance.

Type: 
Class
Example
import Dropdown from '@gravityforms/components/html/admin/elements/Dropdown';

function Example() {
     const dropdownInstance = new Dropdown( {
         render: true,
         renderTarget: '#example-target',
     } );
}

Members

(static) handleAsyncSearch

Handles hitting endpoints for lists data according to endpoint arguments passed in options.

Since
  • 1.1.16
Source

(static) parseRestResponse

Handles applying the rest response items as dropdown items.

Since
  • 1.1.16
Source

Methods

(static) bindEvents() → {void}

Binds all the events for the component.

Since
  • 1.1.16
Source
Returns:
Type: 
void

(static) closeDropdown() → {void}

Modifies all needed classes that close the dropdown, and adjust state, plus also calling any callbacks.

Since
  • 1.1.16
Source
Returns:
Type: 
void

(static) dropdownTemplate(options) → {string}

Generates the markup for a dropdown in the admin.

Parameters:
NameTypeDescription
optionsobject

The options for the component template.

Properties
NameTypeDescription
attributesstring

The attributes to add to the wrapper element, space seperated.

containerstring

The container to append the dropdown to.

dropdownListAttributesstring

The attributes to add to the dropdown list element.

hasSearchboolean

Whether or not to show the search input.

listDataArray

The list data for the dropdown.

searchAriaTextstring

The aria text for the search input.

searchInputIdstring

The id for the search input.

searchPlaceholderstring

The placeholder for the search input.

selectorstring

The selector for the dropdown.

triggerAriaIdstring

The id for the trigger aria.

triggerAriaTextstring

The aria text for the trigger.

triggerClassesstring

The classes for the trigger.

triggerIdstring

The id for the trigger.

triggerPlaceholderstring

The placeholder for the trigger.

triggerSelectedstring

The selected item for the trigger.

triggerTitlestring

The title for the trigger.

wrapperClassesstring

The classes for the wrapper, space seperated string.

Since
  • 1.1.16
Source
Returns:
Type: 
string
Example
import { dropdownTemplate } from '@gravityforms/components/html/admin/elements/Dropdown';

function Example() {
     const dropdownTemplateHTML = dropdownTemplate( options );
     document.body.insertAdjacentHTML( 'beforeend', dropdownTemplateHTML );
}

(static) handleA11y(e) → {void}

Handles accessibility for the dropdown.

Parameters:
NameTypeDescription
e
Since
  • 1.1.16
Source
Returns:
Type: 
void

(static) handleBasicSearch(e) → {void}

Does a basic text search on the dropdown items.

Parameters:
NameTypeDescription
e
Since
  • 1.1.16
Source
Returns:
Type: 
void

(static) handleChange(e) → {void}

Handles item selection in the dropdown list.

Parameters:
NameTypeDescription
e
Since
  • 1.1.16
Source
Fires:
Returns:
Type: 
void

(static) handleControl() → {void}

Handles the control trigger being interacted with and either opens or closes the dropdown.

Since
  • 1.1.16
Source
Returns:
Type: 
void

(static) handleMouseenter() → {void}

Opens the dropdown on the hover event.

Since
  • 1.1.16
Source
Returns:
Type: 
void

(static) handleMouseleave() → {void}

Closes the dropdown on mouseleave if reveal type is hover.

Since
  • 1.1.16
Source
Returns:
Type: 
void

(static) handlePosition() → {void}

If autoposition is true, automatically places the dropdown above or below the control based on the viewport.

Since
  • 1.1.16
Source
Returns:
Type: 
void

(static) handleSearch(e) → {void}

Delegates search handling to either basic or async handlers based on search type in options.

Parameters:
NameTypeDescription
e
Since
  • 1.1.16
Source
Returns:
Type: 
void

(static) init() → {void}

Initialize the component.

Since
  • 1.1.16
Source
Fires:
Returns:
Type: 
void

(static) openDropdown() → {void}

Modifies all needed classes that open the dropdown, and adjust state, plus also calling any callbacks.

Since
  • 1.1.16
Source
Returns:
Type: 
void

(static) render() → {void}

Renders the component into the dom.

Since
  • 1.1.16
Source
Returns:
Type: 
void

(static) renderListData() → {void}

Renders the list data into the already rendered dropdown when called.

Since
  • 1.1.16
Source
Returns:
Type: 
void

(static) setup() → {void}

Sets up various dom variables on init, like long title handling.

Since
  • 1.1.16
Source
Returns:
Type: 
void

(static) storeTriggers() → {void}

Stores the dropdown triggers and reveal controls on the instance as HTMLElements.

Since
  • 1.1.16
Source
Returns:
Type: 
void