Katapult Pro Elements

A web component library for both internal and external development, built with Lit and Shoelace.

<katapult-searchable-dropdown>

Dropdown component for selecting from a list of items. This element supports filtering and can be navigated using keyboard shortcuts.

• Up and Down arrow scrolls the dropdown
• Enter selects the currently highlighted item from the dropdown

Slots

Slot	Usage
slot="label"	Displays above the dropdown to label the type of information in the list. Typical label usage is via the label property, however the slot exists for more customization outside of plain text. If both a label slot and label property exist, the slot will take priority (i.e. the property won't do anything).
slot="prefix"	Appears before the searchable section of the dropdown Typical prefix usage slots in an icon
slot="suffix"	Appears at the end of the searchable section, but before the dropdown arrow and the clear icon Typical suffix usage slots in an icon
slot="help-text"	Displays under the dropdown to give more users more context Typical help text usage is via the helpText property, however the slot exists for more customization outside of plain text. If both a help-text slot and helpText property exist, the slot will take priority (i.e. the property won't do anything).

Properties

Name	Description	Type
stayOpenOnSelect stay-open-on-select	Keeps the dropdown open when an item is selected from the list	Boolean
autoFilter auto-filter	Filters down the listed elements based on what the user types in the search section	Boolean
lookLikePaperElement look-like-paper-element	Formats the dropdown to look like the Polymer paper-dropdown-menu	Boolean
open	Indicates if the dropdown section is opened (can be included in the element to start with it open)	Boolean
hoist	Allows the dropdown part of the element to go outside of the containing element	Boolean
filled	Fills the background with a grey color. The color is stored in var(--sl-input-filled-background-color) and can be changed by overwriting this css variable.	Boolean
pill	Creates rounded corners for the dropdown	Boolean
clearable	Includes an icon button that clears user input from the search	Boolean
disabled	Greys out the dropdown and stops users from interacting with it	Boolean
placement	Determines where the dropdown appears in relation to the search box Options include top top-start top-end bottom bottom-start bottom-end right right-start right-end left left-start and left-end This property gets its utility from Shoelace. To see how these locations appear, reference the Placement section of Shoelace's Popup component	String
autocomplete	Indicates to the browser what it can try to autofill. This would include filling in data such as someone's name, address, or phone number based on their saved personal information. This could be used to select someone's name from a dropdown of listed users, for example. Refer to potential values here	String
size	Controls the size of the search element. Options include small medium and large	String
label	The plain text value to place above the input, to descibe the dropdown	String
helpText	The plain text placed under the input, to help users further understand the dropdown content	String
placeholder	The plain text that appears in the input section when nothing has been typed yet	String
value	Indicates the currently selected item in the list. Note: The value and label attributes aren't necessarily the same unless you make them the same. An item's label represents what is displayed in the dropdown, while it's value indicates what it represents.	String
items	The data to populate the dropdown. This should include label value pairs. The value is the data you will likely extract from the dropdown to determine next actions (such as opening a specific page or doing calculations) [ {label: 'HR', value: '_hr_attribute_path'}, {label: 'Internal Ops', value: '_interops_attribute_path'} ]	Array
containingElement	The element that determines where a dropdown can appear. The formatting follows the normal DOM by default. This property is used for edge cases or for clipping a dropdown that doesn't use hoist	Object
renderItem	Allows customization for how each item is rendered. This property expects a function with parameters indicating the current item, its index, and an array of the items (after being filtered if autoFilter is enabled), as well HTML in the return. (item, index, arr) => html`<sl-menu-item value=${item.value} ?disabled=${item.disabled}>${item.label}`;	Function

Events

Name	Description	Event Detail
change	Emitted when the dropdown is cleared or a new item is selected
value-changed	Emitted when the value attribute of the dropdown changes.
user-input	Emitted when the user changes the search string in the input field.	event.detail.value - the current search string
select	Emitted when a new item is selected from the dropdown.	event.detail - the selected item event.cancelable - true

Methods

Name	Description
show()	Shows the dropdown menu.
hide()	Hides the dropdown menu.
clear()	Clears the current value of the dropdown and clears any user input.

Import Statement

import '@katapult-engineering/elements/katapult-searchable-dropdown.js';