Construit sur l’UI SDK 0.1.0-beta.1 de Vercel. Son API peut changer.
Tree
Une arborescence sur l’UI SDK de Vercel pour fichiers et pages imbriquées, avec chemins de fichiers, cases à cocher, liens et enfants chargés à la demande.
- Composants d’affichage de données
- 7 parties
- 12 exemples
@tabler/icons-react@ui-sdk/core@ui-sdk/reactclass-variance-authority
pnpm dlx shadcn@latest add https://hextaui.com/r/ui-sdk-tree.jsonAjoute le composant, les tokens de thème HextaUI et les composants HextaUI dont il dépend.
Ajoutez les tokens de thème à votre CSS global, si ce n’est pas déjà fait.
Installez les dépendances.
pnpm add @ui-sdk/react@0.1.0-beta.1 @ui-sdk/core@0.1.0-beta.1 @tabler/icons-react class-variance-authority cnCopiez et collez le code suivant dans votre projet.
components/ui/ui-sdk-tree.tsx Mettez à jour les chemins d’import selon la configuration de votre projet.
UI SDK ajoute un peu de CSS dans une couche de cascade nommée ui-sdk. Déclarez cette couche en haut de votre feuille de style globale, au-dessus de l’import Tailwind, pour que vos classes l’emportent.
Un élément contenant un TreeGroup est une branche. Donnez à chaque élément une value unique et à l’arbre un nom accessible. Le focus reste sur l’élément, et son label est la ligne visible : les styles sélectionné, courant et focus s’appliquent donc au label.
Passez items sans enfants, et l’arbre affiche pour vous des lignes stylées avec chevrons. Chaque élément a une value, un label et des children facultatifs.
Passez paths pour un explorateur de fichiers, dossiers en premier. Avec activation="automatic", les flèches sélectionnent, et un onAction qui renvoie une promesse marque la ligne en attente jusqu’à sa résolution.
Avec mode="multiple", Cmd ou Ctrl-clic bascule un élément et Maj étend une plage. expandOnPress={false} laisse le dépliage au chevron et aux flèches.
Ajoutez checkable et un TreeItemCheckbox dans chaque label. Cocher une branche coche tout ce qu’elle contient, et une branche cochée en partie affiche un tiret.
Les éléments avec un href s’affichent comme des liens. Avec mode="none" et current, la page courante reçoit aria-current, ses parents s’ouvrent et elle prend l’arrêt de tabulation.
Marquez un élément branch avant que ses enfants existent, et loadChildren s’exécute à sa première ouverture. Le chevron devient un spinner pendant le chargement, et une icône de nouvel essai en cas d’échec. Archive échoue une fois.
variant="lines" trace un guide de retrait pour chaque groupe ouvert, et size="sm" rend les lignes moins hautes.
Un contrôleur issu de createTreeController() déplie, replie, sélectionne et révèle des éléments depuis n’importe où.
Avec hiddenUntilFound, les groupes fermés restent dans la page : la recherche du navigateur trouve Phobos et ouvre Mars pour l’afficher.
Un élément désactivé peut encore prendre le focus, pour que les lecteurs d’écran le trouvent, mais il ne peut être ni sélectionné, ni coché, ni ouvert.
Les lignes sont décalées depuis la droite, le chevron pointe à gauche, et les flèches gauche et droite s’inversent.
| Touche | Action |
|---|---|
| ↓↑ | Passe à l’élément visible suivant ou précédent. |
| → | Ouvre une branche ou passe à son premier enfant. |
| ← | Ferme une branche ou passe à son parent. |
| HomeEnd | Passe au premier ou dernier élément visible. |
| Alt→ | Ouvre une branche et tout ce qu’elle contient. |
| * | Ouvre toutes les branches voisines de celle ciblée. |
| Enter | Sélectionne l’élément et lance son action, ou suit son lien. |
| Space | Coche l’élément si l’arbre est cochable, sinon le sélectionne. |
| Shift↓ | Étend une sélection multiple. |
| ⌘A | Sélectionne tous les éléments visibles en mode multiple. |
L’arbre suit le motif WAI-ARIA de l’arborescence avec un seul arrêt de tabulation. Tab arrive sur la page courante, l’élément sélectionné ou le premier élément. Taper une lettre passe à l’élément suivant qui commence par elle. Pendant un onAction lent, les lecteurs d’écran entendent pendingAnnouncement au bout d’une seconde : réglez-le dans la langue de votre page.
Les groupes ne s’ouvrent et se ferment en hauteur que si le mouvement est autorisé. Sur écran tactile, les lignes sont plus hautes, et en mode couleurs forcées les lignes sélectionnée et courante reçoivent un contour.
Chaque partie enveloppe la partie UI SDK du même nom et accepte toutes ses props, y compris render et un className qui peut être une fonction de son état.
| Prop | Type | Par défaut |
|---|---|---|
itemsToute la hiérarchie. Sans enfants, l’arbre en affiche des lignes stylées. | TreeItemData[] | – |
pathsChemins de fichiers. Les dossiers deviennent des branches ; un chemin finissant par / est un dossier vide. | string[] | – |
mode | "single" | "multiple" | "none" | "single" |
value | string | string[] | null | – |
defaultValue | string | string[] | null | – |
onValueChange | (value, details) => void | – |
activation | "automatic" | "manual" | "manual" |
expanded | string[] | – |
defaultExpanded | string[] | – |
onExpandedChange | (expanded, details) => void | – |
expandOnPress | boolean | true |
checkable | boolean | false |
checked | string[] | – |
defaultChecked | string[] | – |
onCheckedChange | (checked, details) => void | – |
checkStrategy | "leaf" | "trunk" | "branch" | "independent" | "leaf" |
onActionS’exécute à l’appui ou avec Entrée. Renvoyez une promesse pour marquer l’élément en attente. | (value, details) => unknown | – |
pendingAnnouncement | string | – |
loadChildren | (value, { signal }) => Promise<unknown> | – |
current | string | null | – |
disabled | boolean | false |
hiddenUntilFound | boolean | false |
keepMounted | boolean | false |
variant | "default" | "lines" | "default" |
size | "default" | "sm" | "default" |
controllerIssu de createTreeController(). | TreeController | – |
| Attribut | Description |
|---|---|
data-slot="tree" | Cible l’arbre en CSS. |
data-variant | La variante : default ou lines. |
data-size | La taille : default ou sm. |
--tree-row-height | La hauteur de chaque ligne, réglée par size. |
--tree-indent | Le retrait de chaque niveau. |
| Prop | Type | Par défaut |
|---|---|---|
valueUnique dans l’arbre. | string | – |
branchÀ définir pour une branche dont les enfants se chargent plus tard. | boolean | – |
disabled | boolean | false |
labelLe texte que la saisie rapide recherche quand le label n’est pas du texte brut. | string | – |
render | ReactElement | (props, state) => ReactElement | – |
| Attribut | Description |
|---|---|
data-slot="tree-item" | Cible un élément en CSS. Il porte le focus. |
data-level | La profondeur, à partir de 1. |
data-branch | Présent sur une branche. |
data-expanded | Présent tant qu’une branche est ouverte. |
--tree-level | La profondeur, pour décaler une liste à plat. |
| Prop | Type | Par défaut |
|---|---|---|
render | ReactElement | (props, state) => ReactElement | – |
| Attribut | Description |
|---|---|
data-slot="tree-label" | Cible une ligne en CSS. |
data-selected | Présent tant que l’élément est sélectionné. |
data-current | Présent sur l’élément de la page courante. |
data-expanded | Présent tant qu’une branche est ouverte. |
data-pending | Présent pendant l’exécution du onAction de l’élément. |
data-disabled | Présent lorsque l’item est désactivé. |
| Prop | Type | Par défaut |
|---|---|---|
childrenPar défaut, un chevron, un spinner pendant le chargement et une icône de nouvel essai après un échec. | ReactNode | (state) => ReactNode | – |
| Attribut | Description |
|---|---|
data-slot="tree-indicator" | Cible le chevron en CSS. |
data-loading | Présent pendant le chargement des enfants. |
data-failed | Présent après l’échec du chargement des enfants. |
| Prop | Type | Par défaut |
|---|---|---|
childrenPar défaut, une coche, ou un tiret si mixte. | ReactNode | (state) => ReactNode | – |
| Attribut | Description |
|---|---|
data-slot="tree-checkbox" | Cible la case à cocher en CSS. |
data-checked | Présent tant que coché. |
data-indeterminate | Présent tant qu’une branche est cochée en partie. |
| Prop | Type | Par défaut |
|---|---|---|
keepMounted | boolean | – |
hiddenUntilFound | boolean | – |
| Attribut | Description |
|---|---|
data-slot="tree-group" | Cible un groupe en CSS. |
data-open | Présent tant que l’élément est ouvert. |
--tree-group-height | La hauteur du groupe pendant l’animation. |
- AvatarDes photos d’utilisateurs avec initiales en repli, badges de statut et groupes empilés qui se réduisent en compteur.
- BadgeDes libellés de statut avec pastilles colorées, des tags amovibles qui se referment en glissant et des compteurs qui défilent vers leur nouvelle valeur.
- CardUne surface pour regrouper du contenu, avec trois variantes, médias bord à bord, rayons concentriques et liens sur toute la carte.
- ChartDes graphiques Recharts aux couleurs du thème, avec une infobulle et une légende qui lisent leurs libellés depuis une seule config, et une navigation au clavier avec anneau de focus visible.
- Data tableUn tableau pour de vraies données, avec tri, recherche, sélection de lignes, colonnes épinglées, en-tête fixe et pagination.
- ItemUne ligne de média, de texte et d’actions pour les listes, réglages et sélecteurs, avec une surface groupée et une surbrillance de survol qui glisse d’une ligne à l’autre.