List
Organize items into a structured, vertical format
Source ↗️ Report Issue ↗️Use the List
component to create a list of select and searchable grouped items, with optional icons and additional labels.
- Create issue
- Knowledge base
- Switch theme
A List
component expects an array of objects with an items
property. The items
must be an array of objects, where each object has a name
property, and either a value
or href
property:
value
: Use thevalue
property if you want to handle user action from JavaScript.href
: Use thehref
property if you want the list item to behave as a link.
To handle select events, listen to the listOnSelect
event in Astro, or use the onSelect
prop for Svelte and React components. The event
object returns the following three properties:
Items with Icons and Additional Labels
List items can take various additional properties to change their appearance. You can use the icon
and subText
properties on each item
to create items with icons, or specify an additional label:
- Create issue
- Knowledge base
-
Switch theme
Grouped Items
Items can be grouped by introducing new objects with the items
property. To set the group’s title, specify the title
property:
- Suggestions
- Create issue
- Knowledge base
-
Switch theme
- Settings
- Profile
- Preferences
- Sign out
Disabled and Selected States
To change the state of list items, use the selected
and disabled
props:
- Suggestions
- Create issue
- Knowledge base
-
Switch theme
- Settings
- Profile
- Preferences
- Sign out
Scrolling Lists
In case of long lists, you might want to restrict the height of your List
component. This can be done by using the maxHeight
prop that accepts a valid CSS value:
- Suggestions
- Create issue
- Knowledge base
-
Switch theme
- Settings
- Profile
- Preferences
- Sign out
Searchable Lists
The List
component also has a built-in search functionality. To display the search bar, you can add the showSearchBar
prop to your List
component. Optionally, you can also set the following props to customize the search experience:
showSearchBarIcon
: Display a search icon inside the search bar.searchBarPlaceholder
: Set a placeholder text.noResultsLabel
: Set the label when no search results are found.
- Suggestions
- Create issue
- Knowledge base
-
Switch theme
- Settings
- Profile
- Preferences
- Sign out
API
Prop | Purpose |
---|---|
showSearchBar | Displays a search bar above the list items. Defaults to false . |
showSearchBarIcon | Displays a search icon in the search bar. Defaults to false . |
searchBarPlaceholder | Sets a placeholder for the search bar. |
noResultsLabel | Sets the label for 0 search results. Defaults to "No results" . |
maxHeight | Sets a maximum height for the list, making it scrollable. |
id | Pass an ID for the list. |
className | Pass additional CSS classes for the list. |
wrapperClassName | Pass additional CSS classes for the container of the list. (Only applicable to lists with search bars) |
itemGroups.title | Sets a title for the item group. |
itemGroups.items.name | Sets the name of the list item that is displayed. |
itemGroups.items.value | Sets a value for the list item. |
itemGroups.items.href | Sets a URL for the list item to be used as a link. |
itemGroups.items.target | If the href property is set, use this property to change the behavior of the link. |
itemGroups.items.selected | Sets the list item as active. |
itemGroups.items.disabled | Disables the list item. |
itemGroups.items.icon | Sets an icon for the list item. |
itemGroups.items.subText | Sets an additional label for the list item. |
Svelte & React Prop | Purpose |
---|---|
onSelect | Attach an on-select event listener that is triggered when an item is selected. |
Request improvement for this page