List

Grundlagen

Die List bildet den strukturierten Rahmen für sogenannte ListItems. Alternativ können in der List Elemente in einer Table dargestellt werden, wenn eine tabellarische Ansicht mit Spalten sinnvoll ist.

Ein ListItem ist ein Eintrag in der List und repräsentiert ein spezifisches Element einer übergeordneten Kategorie (z. B. Domains, E-Mail-Adressen, Projekte …). Dabei werden nur die Informationen angezeigt, die notwendig sind, um das jeweilige Element zu verstehen.

Die List fasst alle ListItems bzw. Tabelleneinträge zusammen und stellt Funktionen wie Sortierung, Filterung und Suche bereit. Zusätzlich kann der User über einen „Mehr anzeigen“-Button steuern, wie viele ListItems gleichzeitig angezeigt werden.

Best Practices

Achte bei der Verwendung einer List darauf, dass...

• eine passende Ansicht angeboten wird. Eine Rasteransicht ist z. B. sinnvoll, wenn das Bild eines ListItems für den Userflow entscheidend ist. Gibt es mehrere Anwendungsfälle, sollte der User zwischen verschiedenen Ansichten wechseln können.
• eine Standardsortierung gewählt wird, die dem häufigsten Anwendungsfall entspricht (z. B. „Neueste zuerst“ bei einer Änderungshistorie).
• nur Sortieroptionen angeboten werden, die für den User einen echten Mehrwert bieten.
• bei umfangreichen Lists Filter eingesetzt und die Filterkategorien sinnvoll gruppiert werden (z. B. nach Typ, Größe oder Status).

Verwendung

Verwende eine List, um ...

• viele Elemente (z. B. Domains, Projekte, Rechnungspositionen ...) in Form von ListItems kompakt darzustellen.
• einen einfachen Weg zu schaffen, ein spezifisches ListItem über Filter, Sortierung oder Suche zu finden.
• über ListItems zur Detailseite eines Eintrags zu navigieren.

Anwendung

Position

• Die List wird häufig auf Übersichtsseiten eingesetzt, z. B. um alle Domains auf einen Blick darzustellen. Von dort aus können User in die zugehörigen Detailseiten navigieren.
• Sie nimmt immer die volle Breite des Inhalts einer LayoutCard ein.
• Wenn neben der List weiterer Inhalt auf der Seite vorhanden ist, sollte dieser oberhalb platziert werden. Auf diese Weise werden Layout-Verschiebungen durch das Nachladen über den „Mehr anzeigen“-Button vermieden.

Ansichten

Die List unterstützt drei verschiedene Ansichten: Liste, Raster und Tabelle.

In der Listen- und Rasteransicht werden unterschiedliche Varianten des ListItems dargestellt. In der Tabellenansicht verwendet die List die Table-Component. Sind mehrere Ansichten verfügbar, können User über den Ansichts-Button zwischen ihnen wechseln.

• Liste: Besonders geeignet, wenn viele Elemente übersichtlich, platzsparend und gleichzeitig ansprechend dargestellt werden sollen.
• Raster: Sinnvoll, wenn die Anzahl der Elemente überschaubar ist oder die visuelle Darstellung des Elements im Vordergrund steht. Das ListItem sollte hier nur wenige Informationen enthalten.
• Tabelle: Ideal für Daten, die schnell erfassbar sein müssen, während die optische Gestaltung eine untergeordnete Rolle spielt.

Sortierung

Der Sortierungs-Button wird stets links neben dem Filter-Button angezeigt. Die Standardsortierung sollte dem häufigsten Anwendungsfall entsprechen (z. B. „Neueste zuerst“ bei einer Änderungshistorie). Die aktive Sortierung wird im Sortierungs-Button angezeigt (siehe Abschnitt Writing guidelines).

Filter

Ein Klick auf den Filter-Button öffnet ein ContextMenu, in dem Filter aktiviert oder deaktiviert werden können.

• Unterstützt der Filter eine Mehrfachauswahl, werden die Optionen als Checkbox dargestellt.
• Erfordert ein Filter Einzelauswahl, werden die Optionen als RadioGroup angezeigt.
• Jeder aktive Filter wird durch eine Badge visualisiert, der per Klick einzeln entfernt werden kann. Sind mindestens zwei Filter aktiv, erscheint zusätzlich ein “Filter zurücksetzen”-Button.
• Mehrere Filter derselben Kategorie (z. B. Status, Art, Größe, Abteilung …) sollten in einem eigenen Filter-Button zusammengefasst werden. Filter ohne Kategorie können unter einem allgemeinen „Filter“-Button gruppiert werden.

Pagination

Standardmäßig werden maximal 10 ListItems angezeigt. Mit der Option batchSize kann die Anzahl der anfänglichen ListItems angepasst werden. Über den "Mehr anzeigen"-Button können bei Bedarf weitere ListItems nachgeladen werden.

Beachte bei der Anpassung der Pagination, dass ...

• nur in den seltensten Fällen mehr als 10 Einträge gleichzeitig sichtbar sein müssen. Der User kann über Suche, Filter und Sortierung gezielt nach Einträgen suchen.
• eine List, die beim initialen Seitenaufruf viele Einträge darstellt, die Performance beeinträchtigen kann. Gleiches gilt, wenn durch einen Klick auf den “Mehr Anzeigen”-Button viele Einträge auf einmal nachgeladen werden.

Inhalt

ListItems

ListItems sind die zentralen Bestandteile der List. Sie repräsentieren jeweils ein spezifisches Element und können entweder in einer Listen- oder Rasteransicht dargestellt werden.

In der Listenansicht besteht ein ListItem typischerweise aus:

• Avatar: Der Avatar steht am Anfang eines ListItems. Wird ein Icon verwendet, sollte es die Kategorie des dargestellten Elements widerspiegeln (z. B. ein Domain-Icon bei der Kategorie Domain). Falls der User für das Element ein Image hochladen kann, wird dieses angezeigt. Ist kein Image vorhanden, sollten stattdessen Initialen erscheinen.
• Titel: Der Titel gibt den vergebenen Namen wieder.
• Untertitel: Unterhalb der Benennung können weitere Informationen ergänzt werden. Der Aufbau folgt einem festen Muster: Beschreibender Untertitel – 1. Information – 2. Information
• Top Content und Bottom Content: Neben den Basisinformationen verfügt ein ListItem über zusätzliche Bereiche, die flexibel befüllt werden können (siehe Overview: Content Slots).
• Aktionen: Für Interaktionen mit dem ListItem stehen zwei Varianten zur Verfügung. Entweder werden Aktionen über ein ContextMenu angeboten, oder sie erscheinen direkt als Buttons innerhalb des ListItems.
• Accordion-Funktion: Optional kann ein ListItem eine Accordion-Funktion besitzen.

In der Rasteransicht ist die Darstellung kompakter und stärker visuell ausgerichtet. Der Avatar wird hier größer und in eckiger Form angezeigt. Die grundlegenden Funktionen sind vergleichbar mit denen der Listenansicht, allerdings entfällt in diesem Modus der Top Content sowie die Accordion-Funktion.

Tabellenansicht

Wird eine List mit einer Tabellenansicht verwendet, sind die Guidelines der Table zu beachten.

IllustratedMessage

Die IllustratedMessage wird in zwei Anwendungsfällen verwendet:

• Keine Einträge vorhanden: Die List wird durch eine IllustratedMessage ersetzt. Diese lädt den User über einen Button dazu ein, das erste Element zu erstellen.
• Keine Such- oder Filterergebnisse: Anstelle der ListItems zeigt die List eine IllustratedMessage an, die verdeutlicht, dass keine Ergebnisse vorliegen.

Writing Guidelines

Sortierung

Ist die Standardsortierung aktiv, zeigt der Sortierungs-Button lediglich “Sortierung” an. Wählt der User eine spezifische Sortierung aus, wird der Button-Text entsprechend angepasst. Die Sortiermethode sollte so benannt werden, dass sofort ersichtlich ist, nach welchem Kriterium und in welcher Reihenfolge sortiert wird.

Filterung

Aktive Filter werden als Badges dargestellt. Diese sollten selbsterklärend sein. Bei mehrdeutigen Begriffen empfiehlt es sich, zusätzlichen Kontext anzugeben.

Verhalten

List im Modal

Wenn sich eine List im Modal öffnet, sollte das Suchfeld automatisch fokussiert sein, um dem User eine direkte Eingabe zu ermöglichen. Setze dafür auf das Suchfeld die Property autoFocus.

Responsive Layout

Auf kleinen Bildschirmgrößen passt sich der Header der List an. Ansicht und Sortierung werden in einem Icon-Button zusammengefasst, auch die Filter werden unter einem Icon-Button versteckt. Auf besonders kleinen Bildschirmen wandern diese Elemente zusammen mit der Suche eine Zeile nach unten.

Der Inhalt der ListItems bricht in der Regel bei kleineren Bildschirmgrößen um. Der Top Content (siehe Content Slots im Overview) kann mithilfe von ColumnLayouts auf kleinen Bildschirmen ausgeblendet werden. Dabei dürfen jedoch nur Informationen ausgeblendet werden, die der User nicht benötigt, um das ListItem zu verstehen.

Accessibility

Wird eine List als einziger Hauptinhalt auf einer Seite verwendet, ist keine zusätzliche Heading erforderlich. In diesem Fall muss die List über ein aria-label beschrieben werden.

Hat die List hingegen eine eigene Heading, muss diese mit aria-labelledby der List zugeordnet werden.

Playground

Mit typedList<T> lässt sich eine List für einen bestimmten Datentyp erzeugen.

Im Tab Develop stehen verschiedene Anleitungen zum technischen Aufbau bereit.

import {
  ActionGroup,
  AlertBadge,
  Avatar,
  Button,
  ContextMenu,
  Heading,
  IconDomain,
  IconSubdomain,
  MenuItem,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/04-components/structure/list/examples/domainApi";

export default () => {
  const DomainList = typedList<Domain>();

  return (
    <DomainList.List
      batchSize={4}
      aria-label="Domains"
      defaultViewMode="list"
      getItemId={(domain) => domain.id}
    >
      <DomainList.StaticData data={domains} />
      <ActionGroup>
        <Button color="accent">Anlegen</Button>
      </ActionGroup>
      <DomainList.Search />
      <DomainList.Filter
        property="type"
        mode="some"
        name="Typ"
      />
      <DomainList.Sorting
        property="hostname"
        name="Alphabetisch"
        direction="asc"
        directionName="aufsteigend"
        defaultEnabled
      />
      <DomainList.Sorting
        property="hostname"
        name="Alphabetisch"
        direction="desc"
        directionName="absteigend"
      />
      <DomainList.Table>
        <DomainList.TableHeader>
          <DomainList.TableColumn>
            Name
          </DomainList.TableColumn>
          <DomainList.TableColumn>
            Type
          </DomainList.TableColumn>
          <DomainList.TableColumn>
            TLD
          </DomainList.TableColumn>
          <DomainList.TableColumn>
            Hostname
          </DomainList.TableColumn>
        </DomainList.TableHeader>

        <DomainList.TableBody>
          <DomainList.TableRow>
            <DomainList.TableCell>
              {(domain) => domain.domain}
            </DomainList.TableCell>
            <DomainList.TableCell>
              {(domain) => domain.type}
            </DomainList.TableCell>
            <DomainList.TableCell>
              {(domain) => domain.tld}
            </DomainList.TableCell>
            <DomainList.TableCell>
              {(domain) => domain.hostname}
            </DomainList.TableCell>
          </DomainList.TableRow>
        </DomainList.TableBody>
      </DomainList.Table>
      <DomainList.Item
        textValue={(domain) => domain.domain}
        showTiles
      >
        {(domain) => (
          <DomainList.ItemView>
            <Avatar
              color={
                domain.type === "Domain" ? "blue" : "teal"
              }
            >
              {domain.type === "Domain" ? (
                <IconDomain />
              ) : (
                <IconSubdomain />
              )}
            </Avatar>
            <Heading>
              {domain.hostname}
              {!domain.verified && (
                <AlertBadge status="warning">
                  Unverifiziert
                </AlertBadge>
              )}
            </Heading>
            <Text>{domain.type}</Text>

            <ContextMenu>
              <MenuItem>Details anzeigen</MenuItem>
              <MenuItem>Löschen</MenuItem>
            </ContextMenu>
          </DomainList.ItemView>
        )}
      </DomainList.Item>
    </DomainList.List>
  );
}

Ansichten

Die Liste unterstützt die Ansichten Liste, Raster und Tabelle. Wird mehr als eine Ansicht verwendet, kann über ein Menü zwischen den Ansichten gewechselt werden. Die Default-Ansicht wird über das Property defaultViewMode festgelegt.

Listenansicht

Nutze <List.Item />, um die List in der Listenansicht darzustellen.

Rasteransicht

Für die Rasteransicht wird ebenfalls das <List.Item /> verwendet. Nutze showTiles, um diese Ansicht zu aktivieren. Die Listenansicht kann deaktiviert werden, indem showList auf false gesetzt wird.

Über das maxTileWidth-Property lässt sich die maximale Breite der Kacheln steuern.

Tabellenansicht

Nutze <List.Table />, um die List als Table darzustellen.

ListItems

In einer List lassen sich ListItems mit unterschiedlichen Interaktions- und Aufbaumöglichkeiten einsetzen.

Mit Link

Ein ListItem bietet das Property href an, um das Element zu verlinken.

Mit Accordion

Das Accordion-Verhalten wird über die accordion-Property aktiviert. Dadurch lässt sich ein ListItem per Klick ein- oder ausklappen. Der erweiterte Inhalt wird in <Content slot="bottom" /> platziert.

Mit Checkboxen

Checkboxen in einem ListItem werden automatisch am Anfang der Zeile angeordnet. Die Funktionalität der Checkbox wird nicht von der List gesteuert und muss individuell implementiert werden. Achte bei der Implementierung jedoch darauf, dass die gesamte Zeile zur Auswahl des Elements genutzt werden kann. Nutze dafür onAction der List.

Mit Content Slots

In einem ListItem kann zusätzlicher <Content/ > (Top und Bottom Content) platziert werden. Die Position wird über das slot-Property gesteuert.

Mit ColumnLayout

Dem ListItem können die ColumnLayout Properties s, m und l mitgegeben werden, um das Seitenverhältnis sowie das Umbruchverhalten von Header und Content zu steuern.

Da für die ColumnLayout-Spalten auch null gesetzt werden kann, ist es möglich, nicht zwingend benötigten Content in kleineren Ansichten auszublenden. In diesem Fall werden auch die entsprechenden Content Slots nicht angezeigt.

Mit ActionGroup

Verwende eine ActionGroup innerhalb des <Content />, um Buttons in der List zu platzieren.

Einstellmöglichkeiten

Die List bietet Sortierung, Filter, Suche und Pagination an. Detaillierte Anleitungen zu den einzelnen Einstellmöglichkeiten stehen unter dem Develop-Tab der List zur Verfügung.

Sortierung

Nutze <List.Sorting /> innerhalb der List, um eine Sortiermethode anzulegen.

Filter

Über <List.Filter /> lassen sich Filtermöglichkeiten für die List anlegen. Über priority kann eingestellt werden, ob Filter immer sichtbar sein sollen (primary) oder nur in einem "Alle Filter" Modal angezeigt werden (secondary). "Alle Filter" wird automatisch angezeigt, sobald es secondary Filter gibt.

Date Range Filter

Mit dem mode="dateRange" kannst du einen Filter definieren, der es ermöglicht, einen Zeitraum auszuwählen. So lassen sich Einträge gezielt zwischen einem Start- und Enddatum eingrenzen.

Suche

Verwende <List.Search /> innerhalb der List, um ein SearchField anzuzeigen. Standardmäßig wird die Suche automatisch gestartet. Soll die Suche nur beim Drücken auf Enter ausgelöst werden, kann das Property autoSubmit auf false gesetzt werden.

Pagination

Die Pagination ist standardmäßig bei jeder List aktiviert, kann jedoch über hidePagination deaktiviert werden. Über die batchSize-Property kann festgelegt werden, wie viele Einträge gleichzeitig angezeigt werden sollen.

Loading View

Während die Daten einer List initial geladen werden, zeigt die List eine Loading View aus Skeleton-Platzhaltern an. Ohne weitere Angabe wird dafür ein generisches Skeleton verwendet. Über das loadingView-Property eines <List.Item /> (bzw. eines <TableCell /> in der Tabellenansicht) lässt sich diese Ansicht anpassen.

Gestalte die Loading View so, dass sie dem tatsächlichen Inhalt in Aufbau und Größe möglichst nahekommt, und verwende dafür Skeleton und SkeletonText. So wirkt der Übergang von der Lade- zur Inhaltsansicht ruhig und ohne Layout-Sprung.

Empty View

Mit emptyView kann eine benutzerdefinierte Ansicht angezeigt werden, wenn die Liste keine Einträge enthält. So lässt sich beispielsweise eine Illustration mit einem Hinweistext anzeigen, um die Nutzer zu informieren, dass keine Daten vorhanden sind, und ihnen gegebenenfalls Tipps zu geben, wie sie Daten hinzufügen können.

In der Regel sollte als Empty View eine IllustratedMessage verwendet werden, um eine konsistente Nutzererfahrung zu gewährleisten.

Für den Fall, dass eine Suche oder ein Filter kein Ergebnis liefert, kann über emptySearchResultView eine eigene Ansicht angezeigt werden. Wird sie nicht gesetzt, zeigt die List einen passenden, vordefinierten Hinweis an.

Layout-Shift zwischen Loading und Empty View

Loading View (mehrere Skeleton-Zeilen) und Empty View (in der Regel eine einzelne IllustratedMessage) unterscheiden sich in der Höhe. Beim initialen Laden einer leeren Liste entsteht dadurch ein sichtbarer Sprung, sobald von der Lade- zur Leeransicht gewechselt wird.

Ist die List in eine Seite eingebettet, die bereits einen eigenen Ladezustand anzeigt, lässt sich dieser Sprung vermeiden, indem die List beim initialen Laden keinen eigenen Ladezustand rendert. Wie sich das über das disableInitialSuspenseBoundary-Property steuern lässt, ist im Develop-Tab beschrieben.

Kombiniere mit ...

ActionGroup

Verwende <ActionGroup /> innerhalb der List, um eine ActionGroup anzuzeigen. Hier können eine oder mehrere Aktionen definiert werden, die sich direkt auf die Liste beziehen.

Summary

Verwende eine <ListSummary />, um eine Zusammenfassung anzuzeigen, beispielsweise die Gesamtsumme der Beträge. Über das position-Property wird festgelegt, ob die Summary oberhalb oder unterhalb der List erscheint.

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.

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

Rückgabewert der Async Loader Function

Die Funktion muss ein Object mit folgender Struktur zurückgeben:

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:

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

Sorting

Die List unterstützt eine Sortierung nach Properties:

Es gibt außerdem die Möglichkeit, eine eigene Sortierung zu benutzen:

Sorting Properties

Properties

Events

Accessibility