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.
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.StaticData />,
<List.LoaderAsync />, <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.
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 | - | |
emptySearchResultView | ReactNode | - | |
emptyView | ReactNode | - | |
children | ReactNode | - | |
wrapWith | ReactElement<unknown, string | JSXElementConstructor<any>> | - | |
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 | - | |
accordion | boolean | - | |
settingStorageKey | string | - | |
loadingItemsCount | number | - | |
getItemId | GetItemId<never> | - | |
defaultViewMode | ListViewMode | - | |
settingsStorageDefaults | ListSettingsStorageDefaults | - |
Events
| Property | Type | Default | Description |
|---|---|---|---|
onChange | OnListChanged<never, unknown> | - | |
onSelectionChange | ((keys: Selection) => void) | - | Handler that is called when the selection changes. |
onAction | ItemActionFn<never> | - |
Accessibility
| Property | Type | Default | Description |
|---|---|---|---|
aria-label | string | - | |
aria-labelledby | string | - |