DropDownButton JAVASCRIPT UI Component API

DropDownButton Javascript API

Class

DropDownButton

DropDownButton

DropDownButton displays any type of content like components, text, images, etc in a DropDown.

Selector

smart-drop-down-button

Properties

AanimationSpecifies the animation mode for the component. When set to 'none', all animations are disabled. You can retrieve the current animation mode by getting this property, or change it by setting a new value. Use this property to control whether and how animations are applied to the component’s visual updates.
AautoCloseDelaySpecifies the time delay (in milliseconds) before the dropdown menu automatically closes when the dropDownOpenMode property is set to 'auto'. This allows you to control how long the dropdown remains visible after it has been opened and no further interactions are detected.
DdisabledDetermines whether the element is interactive or non-interactive. When enabled, users can interact with the element as intended. When disabled, the element becomes inactive, usually appearing visually distinct and not responding to user input or events.
DdropDownAppendToSpecifies the parent container for the dropDown popup element. This option is useful when a CSS property (such as overflow, z-index, or positioning) applied to one of the ancestor elements is affecting the display or visibility of the dropDown. By setting the parent container explicitly, you can ensure the dropDown renders correctly and is not hidden or clipped by conflicting CSS styles of its parent elements.
DdropDownButtonPositionSpecifies the placement of the dropdown button relative to its parent element, such as aligning it to the left, right, center, or another defined position within the user interface.
DdropDownHeightSpecifies the height of the dropdown menu. When set, this value overrides the default height controlled by CSS variables. By default, the property is an empty string, allowing the component to use CSS variables for height. Use this property to manually set the dropdown height in environments where CSS variables are not supported by the browser.
DdropDownMaxHeightSpecifies the maximum height of the dropdown menu. By default, the value is an empty string, which allows the component to use CSS variables for height customization. If you need to support browsers that do not support CSS variables, explicitly set this property to the desired height (e.g., '300px'). This ensures the dropdown displays with the correct maximum height even in environments without CSS variable support.
DdropDownMaxWidthSpecifies the maximum width of the dropdown menu. By default, this property is an empty string, meaning the component relies on CSS variables to define its width. You should set this property only if the browser you are targeting does not support CSS variables. In such cases, provide a valid CSS value (e.g., "300px" or "50%") to explicitly set the maximum width of the dropdown.
DdropDownMinHeightSpecifies the minimum height of the dropdown component. By default, this property is set to an empty string, which allows the component to use CSS variables for height management. If the browser does not support CSS variables, you can manually assign a specific minimum height using this property to ensure proper rendering.
DdropDownMinWidthSpecifies the minimum width of the dropdown menu. By default, this property is set to an empty string, allowing the component to use CSS variables for styling. If the browser does not support CSS variables, you should provide a specific value (e.g., '200px') for this property to ensure proper rendering and consistent appearance across all browsers.
DdropDownOpenModeSpecifies the direction or behavior in which the dropdown menu will appear when activated (e.g., opening above, below, to the left, or to the right of the trigger element). This setting controls the initial placement and animation of the dropdown when it is opened.
DdropDownOverlayWhen this property is enabled, opening the element's dropdown will render a transparent overlay that appears beneath the dropdown menu but above the rest of the document. This overlay separates the dropdown from the underlying page content, typically preventing interactions with other elements outside the dropdown while it is open.
DdropDownPlaceholderSpecifies the placeholder text that is displayed within the dropdown menu when no option has been selected or when the dropdown is empty. This text provides guidance or context to the user about the expected input or selection.
DdropDownPositionSpecifies the vertical placement of the dropdown menu relative to its trigger element. When set to 'auto', the dropdown automatically selects the optimal position (above or below the trigger) based on the available space in the viewport, ensuring that the menu is fully visible and not clipped by the window edges.
DdropDownWidthSpecifies the width of the dropdown menu. By default, this property is an empty string, allowing the component to use CSS variables for width. If you need to support browsers that do not support CSS variables, set this property explicitly to define the dropdown’s width. Otherwise, leave it empty to leverage CSS variable-based styling.
HhintProvides supplementary helper text displayed beneath the element. This hint appears only when the element is focused, offering contextual guidance to users during interaction.
HhorizontalScrollBarVisibilityControls whether a horizontal scroll bar is displayed within the dropdown menu, allowing users to scroll horizontally if the dropdown’s content exceeds the available width.
LlabelDisplays a label positioned above the element. The label remains constantly visible, providing context or instructions regardless of the element’s state (focused, filled, or empty).
UunlockKeyDefines or retrieves the unlockKey, a unique code required to access or activate the product.
LlocaleSpecifies or retrieves the current language setting, determining which language is used for displaying messages. This property works in tandem with the messages property to select the appropriate set of localized messages based on the chosen language.
LlocalizeFormatFunctionA callback function that allows you to define how messages returned by the Localization Module are formatted. Use this to customize the structure, content, or styling of localized messages before they are displayed or processed in your application.
MmessagesDefines or retrieves an object that contains the localized text strings used throughout the widget interface. This property enables customization of all user-facing text to support different languages and regions. It is typically used together with the locale property to display the widget in the selected language.
OopenedSpecifies whether the popup is currently visible (open) or hidden (closed) on the screen.
PplaceholderSpecifies the placeholder text that appears within the action button container of the element. This text provides guidance or context to the user before any action is taken or value is entered.
PplaceholderTemplateSpecifies the template used as the placeholder within the element's action button container. Accepts a string (displayed as plain text), a function (which returns the desired content dynamically), or an HTMLTemplateElement (allowing for custom HTML markup). This template defines what users see in the action button area when no action is selected or before an action is initiated.
RreadonlyPrevents users from interacting with the element, disabling all mouse, keyboard, and touch events such as clicking, typing, or tapping. The element remains visible but does not respond to any user input or actions.
RresizeIndicatorSpecifies whether the resize indicator, located in the bottom-right corner of the element, is displayed to users. When enabled, users can see and interact with the indicator to manually resize the element; when disabled, the indicator is hidden and resizing via this handle is not available.
RresizeModeSpecifies whether the drop-down menu is resizable by the user. If resizing is enabled, a resize bar will appear on either the top or bottom edge of the drop-down. Users can click and drag this bar to adjust the height of the drop-down menu according to their preference.
RrightToLeftSets or retrieves a value that determines whether the element’s alignment is configured for right-to-left (RTL) text direction, which is commonly used in languages such as Arabic and Hebrew. This property ensures proper display and alignment of content for locales that use RTL scripts.
TthemeSpecifies the theme for the element, which controls its overall appearance, including colors, fonts, and visual style. The selected theme determines how the element is visually presented to users.
UunfocusableIf set to true, the element will be excluded from keyboard navigation and cannot receive focus, either by tabbing or programmatically.
VverticalScrollBarVisibilityControls whether the vertical scroll bar is displayed, allowing users to scroll vertically when content exceeds the visible area. This setting can enable, disable, or automatically show the scroll bar based on content overflow.

Events

AactionButtonClickThis event is triggered when the user clicks on the action button. The action button becomes visible only when the placeholder property is defined. Use this event to handle custom logic in response to user actions.
CcloseThis event is triggered when the dropdown menu is closed, either by user interaction (such as clicking outside the dropdown or selecting an option) or programmatically via code. It can be used to perform actions or cleanup tasks after the dropdown is no longer visible.
CclosingThis event is fired just before the dropdown list is closed. Within the event handler, you have the opportunity to prevent the dropdown from closing by calling event.preventDefault(). This allows you to implement custom logic—such as validating input or prompting the user—before the dropdown is dismissed.
DdropDownButtonClickThis event is triggered whenever a user interacts with the dropdown component by clicking the dropdown button. It signals the opening or toggling of the dropdown menu, allowing you to execute custom logic in response to user engagement with the dropdown interface.
OopenThis event is triggered each time the drop-down menu becomes visible to the user, such as when a user clicks on the drop-down control to expand it and reveal its list of options. It does not fire if the drop-down is already open or when it is closed. Use this event to perform actions that need to occur immediately after the drop-down is displayed.
OopeningThis event is fired just before the dropdown menu is opened, providing an opportunity to intervene in the opening process. Within the event handler, you can call event.preventDefault() to cancel the dropdown from opening. This is useful for implementing custom logic, such as validating conditions before the dropdown is displayed or preventing the dropdown from opening based on user interactions or application state.
RresizeStartThis event is triggered when the user initiates the resizing action on the dropdown component, such as clicking and dragging a resize handle. It marks the beginning of the user's interaction to adjust the dropdown's size.
RresizeEndThis event is triggered when the user completes resizing the dropdown menu, indicating that the resizing action has ended and the final dimensions of the dropdown have been set.

Methods

CcloseCloses the drop-down menu, hiding its list of options from view and resetting its open state to false.
OopenDisplays the drop-down menu, making its options visible and accessible to the user.
RremoveAllClears all items from the dropdown menu, resulting in an empty list with no selectable options.
SscrollToScrolls the dropdown menu to a specified vertical position, ensuring that the desired item or area within the dropdown is brought into view for the user. This function is useful for highlighting or accessing items that are not currently visible due to scrolling.

Properties

animation"none" | "simple" | "advanced"

Specifies the animation mode for the component. When set to 'none', all animations are disabled. You can retrieve the current animation mode by getting this property, or change it by setting a new value. Use this property to control whether and how animations are applied to the component’s visual updates.

Allowed Values

  • "none" - animation is disabled
  • "simple" - ripple animation is disabled
  • "advanced" - all animations are enabled

Default value

"advanced"

Example

Set the animation property. 

 <smart-drop-down-button animation='none'></smart-drop-down-button>

Set the animation property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.animation = 'simple';

Get the animation property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let animation = dropdownbutton.animation;

autoCloseDelaynumber

Specifies the time delay (in milliseconds) before the dropdown menu automatically closes when the dropDownOpenMode property is set to 'auto'. This allows you to control how long the dropdown remains visible after it has been opened and no further interactions are detected.

Default value

100

Example

Set the autoCloseDelay property. 

 <smart-drop-down-button auto-close-delay='50'></smart-drop-down-button>

Set the autoCloseDelay property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.autoCloseDelay = 200;

Get the autoCloseDelay property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let autoCloseDelay = dropdownbutton.autoCloseDelay;

disabledboolean

Determines whether the element is interactive or non-interactive. When enabled, users can interact with the element as intended. When disabled, the element becomes inactive, usually appearing visually distinct and not responding to user input or events.

Default value

false

Example

Set the disabled property. 

 <smart-drop-down-button disabled></smart-drop-down-button>

Set the disabled property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.disabled = false;

Get the disabled property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let disabled = dropdownbutton.disabled;

dropDownAppendTostring

Specifies the parent container for the dropDown popup element. This option is useful when a CSS property (such as overflow, z-index, or positioning) applied to one of the ancestor elements is affecting the display or visibility of the dropDown. By setting the parent container explicitly, you can ensure the dropDown renders correctly and is not hidden or clipped by conflicting CSS styles of its parent elements.

Default value

"null"
Try a demo showcasing the dropDownAppendTo property.

Example

Set the dropDownAppendTo property. 

 <smart-drop-down-button drop-down-append-to='body'></smart-drop-down-button>

Set the dropDownAppendTo property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.dropDownAppendTo = 'null';

Get the dropDownAppendTo property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let dropDownAppendTo = dropdownbutton.dropDownAppendTo;

dropDownButtonPosition"left" | "right" | "top" | "bottom"

Specifies the placement of the dropdown button relative to its parent element, such as aligning it to the left, right, center, or another defined position within the user interface.

Allowed Values

  • "left" - Positions the drop down button on the left side of the element.
  • "right" - Positions the drop down button on the right side of the element.
  • "top" - Positions the drop down button on the top side of the element.
  • "bottom" - Positions the drop down button on the bottom side of the element.

Default value

"right"
Try a demo showcasing the dropDownButtonPosition property.

Example

Set the dropDownButtonPosition property. 

 <smart-drop-down-button drop-down-button-position='left'></smart-drop-down-button>

Set the dropDownButtonPosition property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.dropDownButtonPosition = 'null';

Get the dropDownButtonPosition property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let dropDownButtonPosition = dropdownbutton.dropDownButtonPosition;

dropDownHeightstring | number

Specifies the height of the dropdown menu. When set, this value overrides the default height controlled by CSS variables. By default, the property is an empty string, allowing the component to use CSS variables for height. Use this property to manually set the dropdown height in environments where CSS variables are not supported by the browser.

Default value

""

Example

Set the dropDownHeight property. 

 <smart-drop-down-button drop-down-height='300'></smart-drop-down-button>

Set the dropDownHeight property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.dropDownHeight = 500;

Get the dropDownHeight property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let dropDownHeight = dropdownbutton.dropDownHeight;

dropDownMaxHeightstring | number

Specifies the maximum height of the dropdown menu. By default, the value is an empty string, which allows the component to use CSS variables for height customization. If you need to support browsers that do not support CSS variables, explicitly set this property to the desired height (e.g., '300px'). This ensures the dropdown displays with the correct maximum height even in environments without CSS variable support.

Default value

""

Example

Set the dropDownMaxHeight property. 

 <smart-drop-down-button drop-down-max-height='800'></smart-drop-down-button>

Set the dropDownMaxHeight property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.dropDownMaxHeight = 1000;

Get the dropDownMaxHeight property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let dropDownMaxHeight = dropdownbutton.dropDownMaxHeight;

dropDownMaxWidthstring | number

Specifies the maximum width of the dropdown menu. By default, this property is an empty string, meaning the component relies on CSS variables to define its width. You should set this property only if the browser you are targeting does not support CSS variables. In such cases, provide a valid CSS value (e.g., "300px" or "50%") to explicitly set the maximum width of the dropdown.

Default value

""

Example

Set the dropDownMaxWidth property. 

 <smart-drop-down-button drop-down-max-width='500'></smart-drop-down-button>

Set the dropDownMaxWidth property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.dropDownMaxWidth = 800;

Get the dropDownMaxWidth property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let dropDownMaxWidth = dropdownbutton.dropDownMaxWidth;

dropDownMinHeightstring | number

Specifies the minimum height of the dropdown component. By default, this property is set to an empty string, which allows the component to use CSS variables for height management. If the browser does not support CSS variables, you can manually assign a specific minimum height using this property to ensure proper rendering.

Default value

""

Example

Set the dropDownMinHeight property. 

 <smart-drop-down-button drop-down-min-height='50'></smart-drop-down-button>

Set the dropDownMinHeight property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.dropDownMinHeight = 150;

Get the dropDownMinHeight property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let dropDownMinHeight = dropdownbutton.dropDownMinHeight;

dropDownMinWidthstring | number

Specifies the minimum width of the dropdown menu. By default, this property is set to an empty string, allowing the component to use CSS variables for styling. If the browser does not support CSS variables, you should provide a specific value (e.g., '200px') for this property to ensure proper rendering and consistent appearance across all browsers.

Default value

""

Example

Set the dropDownMinWidth property. 

 <smart-drop-down-button drop-down-min-width='100'></smart-drop-down-button>

Set the dropDownMinWidth property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.dropDownMinWidth = 90;

Get the dropDownMinWidth property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let dropDownMinWidth = dropdownbutton.dropDownMinWidth;

dropDownOpenMode"none" | "default" | "dropDownButton" | "auto"

Specifies the direction or behavior in which the dropdown menu will appear when activated (e.g., opening above, below, to the left, or to the right of the trigger element). This setting controls the initial placement and animation of the dropdown when it is opened.

Allowed Values

  • "none" - The drop down can't be opened.
  • "default" - The drop down opens when the user clicks on the element
  • "dropDownButton" - The element is split in two button: action and drop down buttons. The drop down opens only when the button is clicked. The action button fires a custom event when clicked on. The event can be used to execute a custom operation on click.
  • "auto" - The drop down opens when the element is hovered and closed when not.

Default value

"default"
Try a demo showcasing the dropDownOpenMode property.

Example

Set the dropDownOpenMode property. 

 <smart-drop-down-button drop-down-open-mode='dropDownButton'></smart-drop-down-button>

Set the dropDownOpenMode property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.dropDownOpenMode = 'auto';

Get the dropDownOpenMode property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let dropDownOpenMode = dropdownbutton.dropDownOpenMode;

dropDownOverlayboolean

When this property is enabled, opening the element's dropdown will render a transparent overlay that appears beneath the dropdown menu but above the rest of the document. This overlay separates the dropdown from the underlying page content, typically preventing interactions with other elements outside the dropdown while it is open.

Default value

false

Example

Set the dropDownOverlay property. 

 <smart-drop-down-button drop-down-overlay></smart-drop-down-button>

Set the dropDownOverlay property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.dropDownOverlay = false;

Get the dropDownOverlay property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let dropDownOverlay = dropdownbutton.dropDownOverlay;

dropDownPlaceholderstring

Specifies the placeholder text that is displayed within the dropdown menu when no option has been selected or when the dropdown is empty. This text provides guidance or context to the user about the expected input or selection.

Default value

"No Items"

Example

Set the dropDownPlaceholder property. 

 <smart-drop-down-button drop-down-placeholder='No content'></smart-drop-down-button>

Set the dropDownPlaceholder property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.dropDownPlaceholder = 'Empty';

Get the dropDownPlaceholder property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let dropDownPlaceholder = dropdownbutton.dropDownPlaceholder;

dropDownPosition"auto" | "top" | "bottom" | "overlay-top" | "overlay-center" | "overlay-bottom" | "center-bottom" | "center-top"

Specifies the vertical placement of the dropdown menu relative to its trigger element. When set to 'auto', the dropdown automatically selects the optimal position (above or below the trigger) based on the available space in the viewport, ensuring that the menu is fully visible and not clipped by the window edges.

Allowed Values

  • "auto" - The position is automatically determines by measuring the available distance around the element for the drop down to open freely without being clipped by the edges of the browser. By default the drop down will try to open below the element. If the available space is not enough for the popup to appear it will open in one of the following directions, if possible: top, over.
  • "top" - The drop down opens above the element.
  • "bottom" - The drop down opens under the element.
  • "overlay-top" - The drop down opens above and over the element. The bottom edges of the drop down cover the element.
  • "overlay-center" - The drop down opens at the center, over the element.
  • "overlay-bottom" - The drop down opens under and over the element. The top edges of the drop down cover the element.
  • "center-bottom" - The drop down opens at the center, below the element.
  • "center-top" - The drop down opens at the center, over the element.

Default value

"auto"
Try a demo showcasing the dropDownPosition property.

Example

Set the dropDownPosition property. 

 <smart-drop-down-button drop-down-position='top'></smart-drop-down-button>

Set the dropDownPosition property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.dropDownPosition = 'bottom';

Get the dropDownPosition property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let dropDownPosition = dropdownbutton.dropDownPosition;

dropDownWidthstring | number

Specifies the width of the dropdown menu. By default, this property is an empty string, allowing the component to use CSS variables for width. If you need to support browsers that do not support CSS variables, set this property explicitly to define the dropdown’s width. Otherwise, leave it empty to leverage CSS variable-based styling.

Default value

""

Example

Set the dropDownWidth property. 

 <smart-drop-down-button drop-down-width='300'></smart-drop-down-button>

Set the dropDownWidth property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.dropDownWidth = 500;

Get the dropDownWidth property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let dropDownWidth = dropdownbutton.dropDownWidth;

hintstring

Provides supplementary helper text displayed beneath the element. This hint appears only when the element is focused, offering contextual guidance to users during interaction.

Default value

""

Example

Set the hint property. 

 <smart-drop-down-button hint='Helper text'></smart-drop-down-button>

Set the hint property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.hint = 'Hint';

Get the hint property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let hint = dropdownbutton.hint;

horizontalScrollBarVisibility"auto" | "disabled" | "hidden" | "visible"

Controls whether a horizontal scroll bar is displayed within the dropdown menu, allowing users to scroll horizontally if the dropdown’s content exceeds the available width.

Allowed Values

  • "auto" - The element automatically determines whether or not the horizontal Scroll bar should be visible or not.
  • "disabled" - Disables the horizontal Scroll bar.
  • "hidden" - Hides the horizontal Scroll bar.
  • "visible" - Shows the horizontal Scroll bar even if not necessary.

Default value

"auto"

Example

Set the horizontalScrollBarVisibility property. 

 <smart-drop-down-button horizontal-scroll-bar-visibility='disabled'></smart-drop-down-button>

Set the horizontalScrollBarVisibility property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.horizontalScrollBarVisibility = 'hidden';

Get the horizontalScrollBarVisibility property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let horizontalScrollBarVisibility = dropdownbutton.horizontalScrollBarVisibility;

labelstring

Displays a label positioned above the element. The label remains constantly visible, providing context or instructions regardless of the element’s state (focused, filled, or empty).

Default value

""

Example

Set the label property. 

 <smart-drop-down-button label='Helper text'></smart-drop-down-button>

Set the label property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.label = 'Label';

Get the label property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let label = dropdownbutton.label;

unlockKeystring

Defines or retrieves the unlockKey, a unique code required to access or activate the product.

Default value

""

Example

Set the unlockKey property. 

 <smart-drop-down-button unlock-key=''></smart-drop-down-button>

Set the unlockKey property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.unlockKey = '1111-2222-3333-4444-5555';

Get the unlockKey property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let unlockKey = dropdownbutton.unlockKey;

localestring

Specifies or retrieves the current language setting, determining which language is used for displaying messages. This property works in tandem with the messages property to select the appropriate set of localized messages based on the chosen language.

Default value

"en"

Example

Set the locale property. 

 <smart-drop-down-button locale='de'></smart-drop-down-button>

Set the locale property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.locale = 'en';

Get the locale property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let locale = dropdownbutton.locale;

localizeFormatFunctionfunction | null

A callback function that allows you to define how messages returned by the Localization Module are formatted. Use this to customize the structure, content, or styling of localized messages before they are displayed or processed in your application.

Example

Set the localizeFormatFunction property. 

 <smart-drop-down-button localize-format-function='function(defaultMessage, message, messageArguments){return '...'}'></smart-drop-down-button>

Set the localizeFormatFunction property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.localizeFormatFunction = function(defaultMessage, message, messageArguments){return '...'};

Get the localizeFormatFunction property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let localizeFormatFunction = dropdownbutton.localizeFormatFunction;

messagesobject

Defines or retrieves an object that contains the localized text strings used throughout the widget interface. This property enables customization of all user-facing text to support different languages and regions. It is typically used together with the locale property to display the widget in the selected language.

Default value




"en": {

"propertyUnknownType": "'{{name}}' property is with undefined 'type' member!",

"propertyInvalidValue": "Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!",

"propertyInvalidValueType": "Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!",

"elementNotInDOM": "Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.",

"moduleUndefined": "Module is undefined.",

"missingReference": "{{elementType}}: Missing reference to {{files}}.",

"invalidNode": "{{elementType}}: Invalid parameter '{{node}}' when calling {{method}}."

}

Example

Set the messages property. 

 <smart-drop-down-button messages='{"de":{"propertyUnknownType":"Die Eigenschaft '{{name}}' hat ein nicht definiertes 'type'-Member!","propertyInvalidValue":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualValue}}, Erwarteter Wert: {{value}}!","propertyInvalidValueType":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualType}}, Erwarteter Wert: {{type}}!","elementNotInDOM":"Element existiert nicht in DOM! Bitte fugen Sie das Element zum DOM hinzu, bevor Sie eine Methode aufrufen.","moduleUndefined":"Modul ist nicht definiert.","missingReference":"{{elementType}}: Fehlender Verweis auf {{files}}.","invalidNode":"{{elementType}}: Ungultiger Parameter '{{node}}' beim Aufruf von {{method}}."}}'></smart-drop-down-button>

Set the messages property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.messages = {"en":{"propertyUnknownType":"'{{name}}' property is with undefined 'type' member!","propertyInvalidValue":"Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!","propertyInvalidValueType":"Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!","elementNotInDOM":"Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.","moduleUndefined":"Module is undefined.","missingReference":"{{elementType}}: Missing reference to {{files}}.","invalidNode":"{{elementType}}: Invalid parameter '{{node}}' when calling {{method}}."}};

Get the messages property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let messages = dropdownbutton.messages;

openedboolean

Specifies whether the popup is currently visible (open) or hidden (closed) on the screen.

Default value

false

Example

Set the opened property. 

 <smart-drop-down-button opened></smart-drop-down-button>

Set the opened property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.opened = false;

Get the opened property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let opened = dropdownbutton.opened;

placeholderstring

Specifies the placeholder text that appears within the action button container of the element. This text provides guidance or context to the user before any action is taken or value is entered.

Default value

""
Try a demo showcasing the placeholder property.

Example

Set the placeholder property. 

 <smart-drop-down-button placeholder='Choose:'></smart-drop-down-button>

Set the placeholder property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.placeholder = 'Submit';

Get the placeholder property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let placeholder = dropdownbutton.placeholder;

placeholderTemplateany

Specifies the template used as the placeholder within the element's action button container. Accepts a string (displayed as plain text), a function (which returns the desired content dynamically), or an HTMLTemplateElement (allowing for custom HTML markup). This template defines what users see in the action button area when no action is selected or before an action is initiated.

Try a demo showcasing the placeholderTemplate property.

Example

Set the placeholderTemplate property. 

 <smart-drop-down-button placeholder-template='Choose:'></smart-drop-down-button>

Set the placeholderTemplate property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.placeholderTemplate = Submit;

Get the placeholderTemplate property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let placeholderTemplate = dropdownbutton.placeholderTemplate;

readonlyboolean

Prevents users from interacting with the element, disabling all mouse, keyboard, and touch events such as clicking, typing, or tapping. The element remains visible but does not respond to any user input or actions.

Default value

false

Example

Set the readonly property. 

 <smart-drop-down-button readonly></smart-drop-down-button>

Set the readonly property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.readonly = false;

Get the readonly property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let readonly = dropdownbutton.readonly;

resizeIndicatorboolean

Specifies whether the resize indicator, located in the bottom-right corner of the element, is displayed to users. When enabled, users can see and interact with the indicator to manually resize the element; when disabled, the indicator is hidden and resizing via this handle is not available.

Default value

false

Example

Set the resizeIndicator property. 

 <smart-drop-down-button resize-indicator></smart-drop-down-button>

Set the resizeIndicator property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.resizeIndicator = false;

Get the resizeIndicator property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let resizeIndicator = dropdownbutton.resizeIndicator;

resizeMode"none" | "horizontal" | "vertical" | "both"

Specifies whether the drop-down menu is resizable by the user. If resizing is enabled, a resize bar will appear on either the top or bottom edge of the drop-down. Users can click and drag this bar to adjust the height of the drop-down menu according to their preference.

Allowed Values

  • "none" - Resizing the drop down is not allowed.
  • "horizontal" - Horizontal resizing of the drop down is allowed but not vertical.
  • "vertical" - Vertical resizing of the drop down is allowed but not horizontal.
  • "both" - Resizing the drop down is allowed in all directions.

Default value

"null"
Try a demo showcasing the resizeMode property.

Example

Set the resizeMode property. 

 <smart-drop-down-button resize-mode='horizontal'></smart-drop-down-button>

Set the resizeMode property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.resizeMode = 'vertical';

Get the resizeMode property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let resizeMode = dropdownbutton.resizeMode;

rightToLeftboolean

Sets or retrieves a value that determines whether the element’s alignment is configured for right-to-left (RTL) text direction, which is commonly used in languages such as Arabic and Hebrew. This property ensures proper display and alignment of content for locales that use RTL scripts.

Default value

false
Try a demo showcasing the rightToLeft property.

Example

Set the rightToLeft property. 

 <smart-drop-down-button right-to-left></smart-drop-down-button>

Set the rightToLeft property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.rightToLeft = true;

Get the rightToLeft property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let rightToLeft = dropdownbutton.rightToLeft;

themestring

Specifies the theme for the element, which controls its overall appearance, including colors, fonts, and visual style. The selected theme determines how the element is visually presented to users.

Default value

""

Example

Set the theme property. 

 <smart-drop-down-button theme='blue'></smart-drop-down-button>

Set the theme property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.theme = 'red';

Get the theme property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let theme = dropdownbutton.theme;

unfocusableboolean

If set to true, the element will be excluded from keyboard navigation and cannot receive focus, either by tabbing or programmatically.

Default value

false

Example

Set the unfocusable property. 

 <smart-drop-down-button unfocusable></smart-drop-down-button>

Set the unfocusable property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.unfocusable = false;

Get the unfocusable property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let unfocusable = dropdownbutton.unfocusable;

verticalScrollBarVisibility"auto" | "disabled" | "hidden" | "visible"

Controls whether the vertical scroll bar is displayed, allowing users to scroll vertically when content exceeds the visible area. This setting can enable, disable, or automatically show the scroll bar based on content overflow.

Allowed Values

  • "auto" - The element automatically determines whether or not the horizontal Scroll bar should be visible or not.
  • "disabled" - Disables the horizontal Scroll bar.
  • "hidden" - Hides the horizontal Scroll bar.
  • "visible" - Shows the horizontal Scroll bar even if it is not necessary.

Default value

"auto"

Example

Set the verticalScrollBarVisibility property. 

 <smart-drop-down-button vertical-scroll-bar-visibility='hidden'></smart-drop-down-button>

Set the verticalScrollBarVisibility property by using the HTML Element's instance. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 dropdownbutton.verticalScrollBarVisibility = 'visible';

Get the verticalScrollBarVisibility property. 

 const dropdownbutton = document.querySelector('smart-drop-down-button');
 let verticalScrollBarVisibility = dropdownbutton.verticalScrollBarVisibility;

Events

actionButtonClickCustomEvent

This event is triggered when the user clicks on the action button. The action button becomes visible only when the placeholder property is defined. Use this event to handle custom logic in response to user actions.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onActionButtonClick

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the actionButtonClick event.

Example

Set up the event handler of actionButtonClick event. 

const dropdownbutton = document.querySelector('smart-drop-down-button');
dropdownbutton.addEventListener('actionButtonClick', function (event) {
	// event handling code goes here.
})

closeCustomEvent

This event is triggered when the dropdown menu is closed, either by user interaction (such as clicking outside the dropdown or selecting an option) or programmatically via code. It can be used to perform actions or cleanup tasks after the dropdown is no longer visible.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onClose

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the close event.

Example

Set up the event handler of close event. 

const dropdownbutton = document.querySelector('smart-drop-down-button');
dropdownbutton.addEventListener('close', function (event) {
	// event handling code goes here.
})

closingCustomEvent

This event is fired just before the dropdown list is closed. Within the event handler, you have the opportunity to prevent the dropdown from closing by calling event.preventDefault(). This allows you to implement custom logic—such as validating input or prompting the user—before the dropdown is dismissed.

  • Bubbles Yes
  • Cancelable Yes
  • Interface CustomEvent
  • Event handler property onClosing

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the closing event.

Example

Set up the event handler of closing event. 

const dropdownbutton = document.querySelector('smart-drop-down-button');
dropdownbutton.addEventListener('closing', function (event) {
	// event handling code goes here.
})

dropDownButtonClickCustomEvent

This event is triggered whenever a user interacts with the dropdown component by clicking the dropdown button. It signals the opening or toggling of the dropdown menu, allowing you to execute custom logic in response to user engagement with the dropdown interface.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onDropDownButtonClick

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the dropDownButtonClick event.

Example

Set up the event handler of dropDownButtonClick event. 

const dropdownbutton = document.querySelector('smart-drop-down-button');
dropdownbutton.addEventListener('dropDownButtonClick', function (event) {
	// event handling code goes here.
})

openCustomEvent

This event is triggered each time the drop-down menu becomes visible to the user, such as when a user clicks on the drop-down control to expand it and reveal its list of options. It does not fire if the drop-down is already open or when it is closed. Use this event to perform actions that need to occur immediately after the drop-down is displayed.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onOpen

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the open event.

Example

Set up the event handler of open event. 

const dropdownbutton = document.querySelector('smart-drop-down-button');
dropdownbutton.addEventListener('open', function (event) {
	// event handling code goes here.
})

openingCustomEvent

This event is fired just before the dropdown menu is opened, providing an opportunity to intervene in the opening process. Within the event handler, you can call event.preventDefault() to cancel the dropdown from opening. This is useful for implementing custom logic, such as validating conditions before the dropdown is displayed or preventing the dropdown from opening based on user interactions or application state.

  • Bubbles Yes
  • Cancelable Yes
  • Interface CustomEvent
  • Event handler property onOpening

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the opening event.

Example

Set up the event handler of opening event. 

const dropdownbutton = document.querySelector('smart-drop-down-button');
dropdownbutton.addEventListener('opening', function (event) {
	// event handling code goes here.
})

resizeStartCustomEvent

This event is triggered when the user initiates the resizing action on the dropdown component, such as clicking and dragging a resize handle. It marks the beginning of the user's interaction to adjust the dropdown's size.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onResizeStart

Arguments

evCustomEvent
ev.detailObject
ev.detail.position - An object containing the current left and top positions of the drop down.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Example

Set up the event handler of resizeStart event. 

const dropdownbutton = document.querySelector('smart-drop-down-button');
dropdownbutton.addEventListener('resizeStart', function (event) {
    const detail = event.detail,
        position = detail.position;

	// event handling code goes here.
})

resizeEndCustomEvent

This event is triggered when the user completes resizing the dropdown menu, indicating that the resizing action has ended and the final dimensions of the dropdown have been set.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onResizeEnd

Arguments

evCustomEvent
ev.detailObject
ev.detail.position - An object containing the current left and top positions of the drop down.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Example

Set up the event handler of resizeEnd event. 

const dropdownbutton = document.querySelector('smart-drop-down-button');
dropdownbutton.addEventListener('resizeEnd', function (event) {
    const detail = event.detail,
        position = detail.position;

	// event handling code goes here.
})

Methods

appendChild( node: Node): T

Arguments

nodeNode

The node to be appended

ReturnsNode

close(): void

Closes the drop-down menu, hiding its list of options from view and resetting its open state to false.


Invoke the close method.

const dropdownbutton = document.querySelector('smart-drop-down-button');
dropdownbutton.close();

Try a demo showcasing the close method.

open(): void

Displays the drop-down menu, making its options visible and accessible to the user.


Invoke the open method.

const dropdownbutton = document.querySelector('smart-drop-down-button');
dropdownbutton.open();

Try a demo showcasing the open method.

removeAll(): void

Clears all items from the dropdown menu, resulting in an empty list with no selectable options.


Invoke the removeAll method.

const dropdownbutton = document.querySelector('smart-drop-down-button');
dropdownbutton.removeAll();

Try a demo showcasing the removeAll method.

removeChild( node: Node): T

Arguments

nodeNode

The node to remove.

ReturnsNode

scrollTo( top: number, left: number): void

Scrolls the dropdown menu to a specified vertical position, ensuring that the desired item or area within the dropdown is brought into view for the user. This function is useful for highlighting or accessing items that are not currently visible due to scrolling.

Arguments

topnumber

Y axis coordinate

leftnumber

X axis coordinate


Invoke the scrollTo method.

const dropdownbutton = document.querySelector('smart-drop-down-button');
dropdownbutton.scrollTo(20,20);

CSS Variables

--smart-drop-down-button-default-widthvar()

Default value

"auto"

smartDropDownButton default width

--smart-drop-down-button-default-heightvar()

Default value

"var(--smart-editor-height)"

smartDropDownButton default height

--smart-drop-down-button-drop-down-widthvar()

Default value

"var(--smart-editor-drop-down-width)"

smartDropDownButton drop down width

--smart-drop-down-button-drop-down-heightvar()

Default value

"var(--smart-editor-drop-down-height)"

smartDropDownButton drop down height