Skip to content

KatapultDevelopment/katapult-pro-elements

BranchesTags

Repository files navigation

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

SlotUsage
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

NameDescriptionType
stayOpenOnSelect
stay-open-on-select		Keeps the dropdown open when an item is selected from the listBoolean
autoFilter
auto-filter		Filters down the listed elements based on what the user types in the search sectionBoolean
lookLikePaperElement
look-like-paper-element		Formats the dropdown to look like the Polymer paper-dropdown-menuBoolean
openIndicates if the dropdown section is opened (can be included in the element to start with it open)Boolean
hoistAllows the dropdown part of the element to go outside of the containing elementBoolean
filledFills 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
pillCreates rounded corners for the dropdownBoolean
clearableIncludes an icon button that clears user input from the searchBoolean
disabledGreys out the dropdown and stops users from interacting with itBoolean
placement
  • Determines where the dropdown appears in relation to the search box
  • Options include toptop-starttop-endbottombottom-startbottom-endrightright-startright-endleftleft-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 smallmedium and large
String
labelThe plain text value to place above the input, to descibe the dropdownString
helpTextThe plain text placed under the input, to help users further understand the dropdown contentString
placeholderThe plain text that appears in the input section when nothing has been typed yetString
valueIndicates 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
containingElementThe 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 hoistObject
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

NameDescriptionEvent Detail
changeEmitted when the dropdown is cleared or a new item is selected
value-changedEmitted when the value attribute of the dropdown changes.
user-inputEmitted when the user changes the search string in the input field.event.detail.value - the current search string
selectEmitted when a new item is selected from the dropdown.event.detail - the selected item
event.cancelable - true

Methods

NameDescription
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';

About

A repository of Katapult custom elements, published as an npm package.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages