Composants et blocks
Les familles de composants de waka-ui, les blocks prêts à l'emploi, les façons de les importer et les points d'entrée qui demandent une dépendance en plus.
waka-ui contient plus de 250 composants et plus de 50 blocks. Cette page en donne la carte ; le détail de chaque composant, avec ses variantes et ses propriétés, se consulte sur le design system ui.wakastart.app.
Composants
Un composant est une brique d'interface : un bouton, un champ, une fenêtre. Les composants de base reprennent les noms et le fonctionnement de shadcn/ui et s'appuient sur Radix UI pour l'accessibilité : navigation au clavier, gestion du focus, attributs ARIA. Les composants propres à waka-ui portent le préfixe Waka.
| Famille | Exemples |
|---|---|
| Base | Button, Card, Badge, Avatar, Tabs, Accordion, Separator, Skeleton |
| Formulaires | Input, Textarea, Select, Checkbox, Switch, Form, WakaDateTimePicker, WakaPhoneInput, WakaFileUpload |
| Fenêtres et menus | Dialog, Sheet, Popover, DropdownMenu, Tooltip, Command |
| Navigation | WakaBreadcrumb, WakaStepper, WakaPagination, WakaBottomTabBar |
| Retours | useToast et Toaster, Alert, WakaEmptyState, WakaSpinner |
| Données | DataTable, DataTableAdvanced, WakaTimeline, WakaKanban, WakaTree |
| Graphiques | WakaBarChart, WakaLineChart, WakaPieChart, WakaAreaChart |
| Thème et langue | ThemeSelector, LanguageSelector, WakaFlagIcon |
D'autres familles couvrent des besoins métier plus spécifiques : crédits et paiement, sécurité, supervision technique, gamification. Parcourez-les sur ui.wakastart.app avant de développer un écran : il existe peut-être déjà.
Tableaux de données
DataTable affiche une liste paginée, triable et filtrable à partir d'un tableau d'objets et d'une définition de colonnes. Le type ColumnDef est exporté par @wakastellar/ui : vous n'avez pas à installer TanStack Table vous-même.
"use client";
import { DataTable, type ColumnDef } from "@wakastellar/ui";
type Member = { name: string; email: string; role: string };
const columns: ColumnDef<Member>[] = [
{ accessorKey: "name", header: "Nom" },
{ accessorKey: "email", header: "E-mail" },
{ accessorKey: "role", header: "Rôle" },
];
export function MembersTable({ members }: { members: Member[] }) {
return (
<DataTable
data={members}
columns={columns}
pagination={{ mode: "client", pageSize: 20 }}
toolbar={{ showSearch: true, showColumnToggle: true }}
/>
);
}Pour une pagination côté serveur, passez mode: "server" avec totalItems, currentPage et onPageChange. DataTableAdvanced ajoute l'édition en ligne, le regroupement et l'export.
Blocks
Un block est un écran ou une grande section d'écran, assemblé à partir de composants : un en-tête, une barre latérale, une page de profil. Vous lui passez des données et des fonctions de rappel ; il ne charge rien lui-même.
| Usage | Exemples |
|---|---|
| Structure de l'application | WakaHeader, WakaSidebar, SidebarLayout, Footer, Layout |
| Compte et organisation | profil, paramètres, gestion des utilisateurs, formulaire d'équipe, WakaApiKeysManager |
| États et erreurs | WakaErrorPage, Error404Page, NoDataState, NoResultsState, ErrorState |
| Tableaux de bord | tableaux de bord, indicateurs clés, calendrier, Kanban |
| Contenus | FAQ, page d'accueil, grille tarifaire, notes de version |
Un block se branche sur vos données Wakastart par ses propriétés. Par exemple, WakaApiKeysManager affiche une liste de clés et appelle onCreate, onRevoke et onRotate : c'est à votre application d'appeler l'API, comme décrit dans Proposer les clés dans votre wakapp.
Important
Le block Login dessine un formulaire e-mail et mot de passe. Avec Wakastart, l'utilisateur saisit son mot de passe sur la page de connexion de la plateforme, jamais dans votre application : suivez Authentification pour la connexion, et personnalisez cette page avec un thème de connexion.
Importer un composant
Trois écritures sont possibles :
// 1. Le point d'entrée principal : tous les composants, blocks, fournisseurs et hooks.
import { Button, DataTable, WakaProvider } from "@wakastellar/ui";
// 2. Un composant seul, par le nom de son dossier.
import { Button } from "@wakastellar/ui/components/button";
// 3. Un block seul.
import { WakaErrorPage } from "@wakastellar/ui/blocks/error-pages";Le point d'entrée principal est le plus simple ; c'est lui qui demande recharts et react-hook-form à l'installation. Les imports par composant ne chargent que le composant visé.
Tous les modules de waka-ui sont marqués "use client" : vous pouvez les utiliser depuis un composant serveur, ils deviennent des composants client à cet endroit. Une propriété qui reçoit une fonction (onClick, onPageChange) impose en revanche que le composant parent soit lui-même un composant client.
Points d'entrée dédiés
Les composants les plus lourds ont leur propre point d'entrée. Installez la dépendance indiquée avant de les importer.
| Point d'entrée | Contenu | À installer |
|---|---|---|
@wakastellar/ui/charts | graphiques WakaBarChart, WakaLineChart, WakaPieChart… | recharts@^2 |
@wakastellar/ui/rich-text | éditeur de texte riche WakaRichTextEditor | @tiptap/react, @tiptap/starter-kit, @tiptap/extension-link, @tiptap/extension-text-align, @tiptap/extension-underline (3.30.5 ou plus, avant 4) |
@wakastellar/ui/export | export et import des tableaux : useDataTableExport, useDataTableImport | exceljs pour le format xlsx ; jspdf et jspdf-autotable pour le PDF. CSV, JSON et XML sans dépendance |
@wakastellar/ui/doc | rendu de documentation : WakaDocRenderer, WakaDocShell… | react-markdown, remark-gfm, rehype-slug, rehype-raw ; pour l'édition, en plus les paquets tiptap et tiptap-markdown |
@wakastellar/ui/editor | éditeur de blocs WakaEditor, sur Plate | platejs, @platejs/basic-nodes, @platejs/table, @platejs/layout, @platejs/callout (52 ou plus) |
@wakastellar/ui/md-editor | éditeur Markdown WakaMdEditor | rien : moteur et styles inclus |
@wakastellar/ui/md-editor embarque son moteur complet (formules, diagrammes, coloration syntaxique) : chargez-le à la demande, côté navigateur seulement.
"use client";
import dynamic from "next/dynamic";
const WakaMdEditor = dynamic(
() => import("@wakastellar/ui/md-editor").then((m) => m.WakaMdEditor),
{ ssr: false },
);
export function NoteEditor({ initial, onChange }: { initial: string; onChange: (md: string) => void }) {
return <WakaMdEditor defaultValue={initial} onChange={onChange} />;
}Pour aller plus loin
- ui.wakastart.app : le catalogue des composants et des blocks, avec des exemples interactifs.
- Référence de waka-ui : tous les points d'entrée du paquet.
- Appliquer le thème