Introduction

Un conteneur de mise en page CSS Grid hautement responsive et flexible pour construire des structures de page et des interfaces en grille. Disposez les éléments enfants avec un nombre explicite de colonnes ou de lignes, ou laissez-les s'adapter dynamiquement selon une largeur minimale d'enfant sans media queries explicites. Prend en charge pleinement les configurations responsives par breakpoint.

Utilisation

Le composant Grid est également intégré en tant que bloc grid dans le Page Builder, permettant aux auteurs et développeurs de construire facilement des structures responsives, listes de cartes et contrôles côte à côte directement dans le CMS.

Colonnes fixes

---

• Colonnes & lignes dynamiques : Spécifiez facilement les pistes via des valeurs numériques ou des définitions de template CSS.
• Mise à l'échelle Auto-Fit : Définissez un seuil de largeur minimale (minChildWidth) pour que le conteneur fasse fluer les enfants en colonnes selon l'espace.
• Breakpoints responsives : Support natif pour les breakpoints (base, sm, md, lg, xl, 2xl).
• Rendu polymorphe : Rendu via as comme balise HTML sémantique, ou délégation des styles à un enfant via asChild.
• Performance sans décalage : Les styles compilent en utilitaires Panda CSS statiques optimisés, sans surcoût JS client.

---

Ces exemples illustrent comment structurer des composants grid en code (JSX/TSX) et via JSON Page Builder.

Spécifie un nombre explicite de colonnes affichant trois éléments côte à côte. Idéal pour grilles de fonctionnalités, métriques ou navigation.

JSX / TSX

import { Grid } from "../components/ui";

export default function Example() {
  return (
    <Grid columns={3} gap="4">
      <div>1</div>
      <div>2</div>
      <div>3</div>
    </Grid>
  );
}

Page Builder JSON

{
  "type": "grid",
  "columns": 3,
  "gap": "4",
  "children": [
    { "type": "text", "content": "1" },
    { "type": "text", "content": "2" },
    { "type": "text", "content": "3" }
  ]
}

---

2. Colonnes Auto-Fit par largeur minimale

Les colonnes sont ajoutées ou retirées automatiquement au redimensionnement. Évite de définir des breakpoints, garantissant des conteneurs de cartes totalement responsives.

JSX / TSX

import { Grid } from "../components/ui";

export default function Example() {
  return (
    <Grid minChildWidth="120px" gap="4">
      <div>Card A</div>
      <div>Card B</div>
      <div>Card C</div>
    </Grid>
  );
}

Page Builder JSON

{
  "type": "grid",
  "minChildWidth": "120px",
  "gap": "4",
  "children": [
    { "type": "text", "content": "Card A" },
    { "type": "text", "content": "Card B" },
    { "type": "text", "content": "Card C" }
  ]
}

---

3. Allocation de colonnes responsive

Affiche une seule colonne sur mobile, passe à deux sur tablette et trois sur desktop.

Programmatic Usage (TSX)

import { Grid } from "@/components/ui";

export default function ResponsiveGrid() {
  return (
    <Grid columns={{ base: 1, md: 2, lg: 3 }} gap="6">
      <div>Responsive Grid Item 1</div>
      <div>Responsive Grid Item 2</div>
      <div>Responsive Grid Item 3</div>
    </Grid>
  );
}

Page Builder Configuration (CMS JSON)

JSX / TSX

import { Grid } from "../components/ui";

export default function Example() {
  return (
    <Grid columns={{ base: 1, md: 2, lg: 3 }} gap="6">
      <div>Responsive Grid Item 1</div>
      <div>Responsive Grid Item 2</div>
      <div>Responsive Grid Item 3</div>
    </Grid>
  );
}

Page Builder JSON

{
  "type": "grid",
  "columns": "{\"base\": 1, \"md\": 2, \"lg\": 3}",
  "gap": "6",
  "children": [
    { "type": "text", "content": "Responsive Grid Item 1" },
    { "type": "text", "content": "Responsive Grid Item 2" },
    { "type": "text", "content": "Responsive Grid Item 3" }
  ]
}

---

4. Espacements colonne et ligne séparés

Les espaces entre lignes et colonnes se configurent indépendamment pour créer des grilles asymétriques ou un emballage de lignes plus serré.

JSX / TSX

import { Grid } from "../components/ui";

export default function Example() {
  return (
    <Grid columns={2} columnGap="6" rowGap="2">
      <div>1</div>
      <div>2</div>
      <div>3</div>
      <div>4</div>
    </Grid>
  );
}

Page Builder JSON

{
  "type": "grid",
  "columns": 2,
  "columnGap": "6",
  "rowGap": "2",
  "children": [
    { "type": "text", "content": "1" },
    { "type": "text", "content": "2" },
    { "type": "text", "content": "3" },
    { "type": "text", "content": "4" }
  ]
}

---

Props

Propriété	Type / Type de champ CMS	Défaut	Description
columns	number | string | Responsive<...>	-	Nombre de colonnes explicite (ex. 3 ou "3"). Accepte un objet breakpoint ou une chaîne JSON dans le CMS (ex. '{"base": 1, "md": 3}'). Prioritaire sur minChildWidth.
rows	number | string | Responsive<...>	-	Nombre de lignes explicite. Utile pour des layouts de template structurés.
minChildWidth	number | string | Responsive<...>	-	Seuil de largeur pour colonnes auto-fit (ex. "120px", "16rem"). Ignoré si columns est défini.
gap	string | number | Responsive<...>	"8px"	Espace séparant les cellules consécutives.
columnGap	string | number | Responsive<...>	-	Espace horizontal uniquement entre colonnes.
rowGap	string | number | Responsive<...>	-	Espace vertical uniquement entre lignes.
class	string	-	Remplacements de classes CSS personnalisées.
children	any | list	-	Collection de blocs de layout ou visuels imbriqués dans la grille.

Valeurs responsives : Responsive<T> accepte une valeur plate ou un objet mappé par breakpoints (ex. { base: 1, md: 2, lg: 3 }). Le design system prend en charge base, sm, md, lg, xl et 2xl.

---

Hydration & Architecture

Tier-3 Presentational Layout Primitive

Le composant Grid est classé comme Composant Presentational Tier-3 dans l'architecture Island Hydration. Il ne possède aucun état réactif client et ne gère aucun événement. Par conséquent :

• Il ne monte jamais d'îlot interactif client.
• Compile directement en HTML statique sans JS, sans surcoût de bundle.
• Un prop interactive explicite n'est ni requis ni pris en charge.

Developer Implementation Notes

• Intégration Panda CSS : Traduit columns, rows et gaps en utilitaires grid Panda CSS avec classes atomiques performantes.
• Chaînes JSON responsives : Dans Sveltia CMS, les valeurs responsives doivent être écrites en chaînes JSON (ex. '{"base": 1, "md": 2}'). Elles sont parsées automatiquement au runtime.

Accessibility Compliance

• Flux DOM naturel : Le conteneur préserve la navigation clavier séquentielle (Tab) et l'ordre de lecture DOM. Alignez les enfants avec la séquence visuelle logique pour préserver l'accessibilité.