Die List Component erlaubt das Rendern und Verwalten von Daten in einer strukturierten Liste. Daten können entweder statisch oder asynchron, z. B. über eine API, geladen werden.
Möglichkeiten zum Laden von Daten
1. Statische Daten
Für die Anzeige statischer Daten kann die Component <StaticData /> verwendet
werden:
dataArray: Ein Array mit den Daten, die direkt in der List gerendert werden.- Diese Variante ist einfach und benötigt keine zusätzliche Logik für das Nachladen oder Filtern.
2. Dynamische Daten (Asynchrones Laden)
Mit <LoaderAsync> können Daten dynamisch aus einer API oder anderen
asynchronen Quellen nachgeladen werden:
3. Laden über Hooks (z.B. TanStack Query oder SWR)
Mit <LoaderHooks> können Daten dynamisch über React Hooks nachgeladen werden.
Der Einsatz von Suspense ist hierbei erforderlich.
Verhalten & Features
- Ladeanimation: Während die Daten geladen werden, wird eine Ladeanimation angezeigt.
- Server-seitige Funktionen:
- Pagination (
manualPagination): Aktiviert das serverseitige Paging. - Sortierung (
manualSorting): Die Sortierung erfolgt auf dem Server. - Filterung (
manualFiltering): Filter werden nicht client-seitig angewendet, sondern an den Server weitergeleitet. - Suche: Kann ebenfalls serverseitig erfolgen.
- Pagination (
Optionen für die Async Loader Function
Die <LoaderAsync>-Component benötigt eine Async Loader Function, die die
Daten anhand von Steuerungsoptionen lädt. Diese Funktion erhält ein
options-Objekt mit den folgenden Parametern:
Struktur des options-Objekts
| Property | Typ | Beschreibung |
|---|---|---|
filtering | { [key: string]: { mode: "all" | "some" | "one"; values: any[] } } | Enthält Filter für die Daten. Jedes Key-Value-Paar repräsentiert eine Filterbedingung für ein Datenfeld. |
searchString | string | Der eingegebene Suchbegriff. |
pagination | { offset: number; limit: number } | Enthält Offset (Startpunkt) und Limit (maximale Anzahl an Datensätzen). |
sorting | { [key: string]: "asc" | "desc" } | Gibt an, nach welchen Datenfeldern sortiert werden soll. |
Rückgabewert der Async Loader Function
Die Funktion muss ein Object mit folgender Struktur zurückgeben:
| Property | Typ | Beschreibung |
|---|---|---|
data | any[] | Array der geladenen Daten. |
itemTotalCount | number | Gesamtanzahl der Datensätze (nur bei Pagination erforderlich). |
Infinite Scroll
Standardmäßig wird die nächste Seite über einen "Mehr anzeigen"-Button nachgeladen. Für sehr lange Listen, in denen ohne konkretes Suchziel gestöbert wird, kann stattdessen Infinite Scroll aktiviert werden: Die nächste Seite wird automatisch geladen, sobald das Ende der Liste in den sichtbaren Bereich scrollt.
- Infinite Scroll ist opt-in und sollte nicht der Default für alle Listen sein. Für kurze oder gezielt durchsuchte Listen ist der "Mehr anzeigen"-Button in der Regel die bessere Wahl.
- Der Mechanismus funktioniert unabhängig davon, ob die Daten statisch,
asynchron oder über Hooks geladen werden, und respektiert
manualPagination. - Während des Nachladens wird ein Ladeindikator am Ende der Liste angezeigt.
Lade- und Leeransichten
Loading View
Während die Daten initial geladen werden, zeigt die List eine Loading View aus
Skeleton-Platzhaltern an. Über loadingView an einem <List.Item /> – oder an
einem <TableCell /> in der Tabellenansicht – kann diese Ansicht angepasst
werden:
Wird kein loadingView gesetzt, verwendet die List ein generisches Skeleton.
Die Loading View gilt in allen View Modes (List, Tiles, Table) und auch für einzelne Items, die nach dem initialen Laden noch suspenden – etwa weil ihr Inhalt eigene Daten nachlädt.
Empty View
emptyView: Wird angezeigt, wenn die Liste keine Einträge enthält.emptySearchResultView: Wird angezeigt, wenn eine Suche oder ein Filter kein Ergebnis liefert.
Ist das jeweilige Property nicht gesetzt, zeigt die List eine passende, vordefinierte Ansicht an.
Initiale Suspense-Boundary
Beim initialen Laden umschließt die List das Laden der Daten standardmäßig mit
einer eigenen Suspense-Boundary
und zeigt währenddessen ihre Loading View an. Über
disableInitialSuspenseBoundary an der Datenquelle (<List.LoaderAsync />,
<List.LoaderAsyncResource />, <List.LoaderHooks />) lässt sich dieses
Verhalten steuern:
| Wert | Verhalten |
|---|---|
false (Default) | Die List rendert beim initialen Laden ihre eigene Loading View (Skeleton). |
true | Die List rendert beim initialen Laden keine eigene Suspense-Boundary. Das Suspending wird an die nächste übergeordnete Suspense-Boundary weitergereicht; die List erscheint erst mit geladenen Daten. |
Wann welchen Wert wählen?
- Belasse den Wert bei
false, wenn die List den Hauptinhalt darstellt oder keine übergeordnete Ladeanzeige existiert. Nutzer erhalten so unmittelbar ein visuelles Feedback direkt in der Liste. - Setze den Wert auf
true, wenn die List in eine Seite oder einen Bereich eingebettet ist, die bzw. der bereits einen eigenen Ladezustand anzeigt. So wird die List atomar dargestellt und der Layout-Shift zwischen Loading und Empty View vermieden.
Zeigt deine Anwendung durchgängig eigene Ladezustände, kannst du true als
Standard für alle Lists festlegen, statt es an jeder Datenquelle zu wiederholen
– siehe <ComponentDefaultsProvider />.
Filter
In der Regel werden Filter für ein Property der List gesetzt:
Die Anzeige des Filter-Values kann angepasst werden, um z. B. Übersetzungen zu ermöglichen:
Es gibt die Möglichkeit, eigene Properties zu verwenden, die nicht in der List
vorkommen . Hierfür muss dem property ein "$" vorangestellt werden:
Filter Properties
| Property | Typ | Beschreibung |
|---|---|---|
defaultSelected | string[] | Array der als default gesetzten Filter |
matcher | FilterMatcher<T, TProp, string> | Definiert eine eigene Filterlogik für die Listenelemente |
mode | "all" | "some" | "one" | Bestimmt, wie mehrere ausgewählte Filterwerte miteinander kombiniert werden |
name | string | Der Anzeigename des Filters |
property | string | Das für die Filterung verwendete Property |
values | string[] | Die Optionen für den Filter |
Sorting
Die List unterstützt eine Sortierung nach Properties:
Es gibt außerdem die Möglichkeit, eine eigene Sortierung zu benutzen:
Sorting Properties
| Property | Typ | Beschreibung |
|---|---|---|
customSortingFn | SortingFn<T> | Möglichkeit eine eigene Sortierfunktion zu definieren |
defaultEnabled | boolean | "hidden" | Bestimmt, ob die Sortierung als default gesetzt wird, bei "hidden" ist die Sortier-Option nicht sichtbar, wird aber im Hintergrund angewendet |
direction | "asc" | "desc" | Auf- oder absteigende Sortierung |
name | string | Der Anzeigename der Sortier-Option |
directionName | string | Der Anzeigename der Sortierrichtung |
property | string | Das für die Sortierung verwendete Property |
Properties
| Property | Type | Default | Description |
|---|---|---|---|
batchSize | number | - | The number of items to be displayed on one page. |
infiniteScroll | boolean | false | Automatically loads the next batch of items when the user scrolls to the end of the list, instead of showing a "Show more" button. |
hidePagination | boolean | false | Hides the pagination controls below the list. |
emptySearchResultView | ReactNode | - | The view rendered when a search or filter returns no results. |
emptyView | ReactNode | - | The view rendered when the list contains no items. |
children | ReactNode | - | |
wrapWith | ReactElement<unknown, string | JSXElementConstructor<any>> | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. |
ref | Ref<HTMLSpanElement> | - | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). @see React Docs |
key | Key | - | |
disallowEmptySelection | boolean | - | Whether the collection allows empty selection. |
disabledKeys | Iterable<Key> | - | The currently disabled keys in the collection (controlled). |
selectionMode | SelectionMode | - | The type of selection that is allowed in the collection. |
selectedKeys | "all" | Iterable<Key> | - | The currently selected keys in the collection (controlled). |
defaultSelectedKeys | "all" | Iterable<Key> | - | The initial selected keys in the collection (uncontrolled). |
selectionBehavior | SelectionBehavior | - | Whether selecting an item replaces the current selection (`"replace"`) or adds to it (`"toggle"`). |
accordion | boolean | false | Makes list items expandable. The expanded content is placed in `<Content slot="bottom" />`. |
settingStorageKey | string | - | The key the lists settings (view mode, search, filters, sorting) are persisted under. Requires a `<SettingsProvider />` — without a key nothing is persisted. |
loadingItemsCount | number | - | The number of skeleton placeholder items rendered while data is loading. Defaults to the lists batch size. |
getItemId | GetItemId<never> | - | Derives a stable ID from an items data. Used to deduplicate items across loaded batches and as the row ID in the table view. |
defaultViewMode | ListViewMode | "list" | The view mode the list starts in. A persisted view mode takes precedence. |
settingsStorageDefaults | ListSettingsStorageDefaults | - | Defaults for how the lists settings are persisted. |
Events
| Property | Type | Default | Description |
|---|---|---|---|
onChange | OnListChanged<never, unknown> | - | Called with the list model whenever its state changes. |
onSelectionChange | ((keys: Selection) => void) | - | Handler that is called when the selection changes. |
onAction | ItemActionFn<never> | - | Called with the items data when the user activates a list item. |
Accessibility
| Property | Type | Default | Description |
|---|---|---|---|
aria-label | string | - | An accessible label for the list. |
aria-labelledby | string | - | The ID of the element labelling the list. |