List

Organize items into a structured, vertical format

Use the List component to create a list of select and searchable grouped items, with optional icons and additional labels.

Preview

Create issue
Knowledge base
Switch theme

---
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>

<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)}
/>

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:

value: Use the value property if you want to handle user action from JavaScript.
href: Use the href 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:

{
    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:

Create issue

(GitHub)
Knowledge base

Learn more
Switch theme

---
// 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:

Suggestions
Create issue

(GitHub)
Knowledge base

Learn more
Switch theme
Settings
Profile
Preferences
Sign out

<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:

Suggestions
Create issue

Issue creation disabled
Knowledge base

Learn more
Switch theme
Settings
Profile
Preferences
Sign out

<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:

Suggestions
Create issue

(GitHub)
Knowledge base

Learn more
Switch theme
Settings
Profile
Preferences
Sign out

<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:

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

(GitHub)
Knowledge base

Learn more
Switch theme
Settings
Profile
Preferences
Sign out

<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

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.

<- Kbd Masonry ->

Request improvement for this page