Search documentation v0.6.1

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.

Preview
How to use Lists in Astro
---
import { List } from 'webcoreui/astro'
const list = [{
items: [
{ name: 'Create issue', value: 'new' },
{ name: 'Knowledge base', href: '/knowledge-base' },
{ name: 'Switch theme', value: 'theme' }
]
}]
---
<List itemGroups={list} />
<script>
import { listen } from 'webcoreui'
listen('listOnSelect', event => console.log(event))
</script>
How to use Lists in Svelte
<script>
import { List } from 'webcoreui/svelte'
const list = [{
items: [
{ name: 'Create issue', value: 'new' },
{ name: 'Knowledge base', href: '/knowledge-base' },
{ name: 'Switch theme', value: 'theme' }
]
}]
</script>
<List
itemGroups={list}
onSelect={event => console.log(event)}
/>
How to use Lists in React
import React from 'react'
import { List } from 'webcoreui/react'
const list = [{
items: [
{ name: 'Create issue', value: 'new' },
{ name: 'Knowledge base', href: '/knowledge-base' },
{ name: 'Switch theme', value: 'theme' }
]
}]
const Component = () => (
<List
itemGroups={list}
onSelect={event => console.log(event)}
/>
)
export default Component

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:

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:

Event object
{
value: 'new', // Value of the clicked item
name: 'Create issue', // Name of the clicked item
list: ul._list_1rduk_1 // HTMLUListElement - the ul which the item belongs to
}

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:

---
// Import icons at the top of your component
// The icon must be an SVG string
import { github, info, moon } from 'webcoreui/icons'
---
<List itemGroups={[{
items: [
{
name: 'Create issue',
value: 'new',
icon: github,
subText: '(GitHub)'
},
{
name: 'Knowledge base',
href: '/knowledge-base',
icon: info,
subText: 'Learn more'
},
{
name: 'Switch theme',
value: 'theme',
icon: moon
}
]
}]} />

Grouped Items

Items can be grouped by introducing new objects with the items property. To set the group’s title, specify the title property:

<List itemGroups={[
{
title: 'Suggestions',
items: [
{
name: 'Create issue',
value: 'new',
icon: gitHubIcon,
subText: '(GitHub)'
},
{
name: 'Knowledge base',
href: '/knowledge-base',
icon: infoIcon,
subText: 'Learn more'
},
{ name: 'Switch theme', value: 'theme', icon: moonIcon }
]
},
{
title: 'Settings',
items: [
{ name: 'Profile', href: '/profile' },
{ name: 'Preferences', href: '/preferences' },
{ name: 'Sign out', value: 'sign-out' }
]
}
]} />

Disabled and Selected States

To change the state of list items, use the selected and disabled props:

<List itemGroups={[
{
title: 'Suggestions',
items: [
{
name: 'Create issue',
value: 'new',
icon: gitHubIcon,
subText: 'Issue creation disabled'
disabled: true
},
{
name: 'Knowledge base',
href: '/knowledge-base',
icon: infoIcon,
selected: true
},
{ ... }
]
},
{ ... }
]} />

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:

<List
itemGroups={[...]}
maxHeight="160px"
/>

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:

<List
itemGroups={[...]}
showSearchBar={true}
showSearchBarIcon={true}
searchBarPlaceholder="Search the app..."
noResultsLabel="Nothing found here..."
/>

API

type ListEventType = {
value: string
name: string
list: HTMLUListElement
}
type ListProps = {
showSearchBar?: boolean
showSearchBarIcon?: boolean
searchBarPlaceholder?: string
noResultsLabel?: string
maxHeight?: string
id?: string
className?: string
wrapperClassName?: string
itemGroups: {
title?: string
items: {
name: string
value?: string
href?: string
target?: '_self' | '_blank' | '_parent' | '_top' | '_unfencedTop'
selected?: boolean
disabled?: boolean
icon?: string
subText?: string
}[]
}[]
}
type SvelteListProps = {
onSelect?: (event: ListEventType) => void
} & ListProps
type ReactListProps = {
onSelect?: (event: ListEventType) => void
} & ListProps
PropPurpose
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 PropPurpose
onSelect Attach an on-select event listener that is triggered when an item is selected.

Request improvement for this page