Typographie

text() rend un morceau de texte à l’une des tailles de la bibliothèque. La variante choisit un élément sensé — variant: 'h2' rend un vrai <h2> — si bien que les titres entrent dans le plan du document sans que personne ait à y penser.

Variantes

Titre 1

Titre 2

Titre 3

Titre 4

Titre 5

Titre 6

Lead — un cran au-dessus du corps de texte, pour la phrase sous un titre.

Body — la valeur par défaut.

Small — des légendes qui restent des phrases.

Caption — les petits caractères.Overline

stack({ gap: 'sm' },
  text({ variant: 'h1' }, 'Titre 1'),
  text({ variant: 'h2' }, 'Titre 2'),
  text({ variant: 'h3' }, 'Titre 3'),
  text({ variant: 'h4' }, 'Titre 4'),
  text({ variant: 'h5' }, 'Titre 5'),
  text({ variant: 'h6' }, 'Titre 6'),
  text({ variant: 'lead' }, 'Lead — un cran au-dessus du corps de texte, pour la phrase sous un titre.'),
  text({ variant: 'body' }, 'Body — la valeur par défaut.'),
  text({ variant: 'small' }, 'Small — des légendes qui restent des phrases.'),
  text({ variant: 'caption' }, 'Caption — les petits caractères.'),
  text({ variant: 'overline' }, 'Overline'),
)

Titres

heading() prend un level de plan et se dimensionne en conséquence. size découple les deux : un <h1> qui ressemble à un h3 reste un h1 pour un lecteur d’écran.

Un titre de niveau 2, dimensionné en conséquence

Un titre de niveau 2, dimensionné comme un h5

stack({ gap: 'sm' },
  heading({ level: 2 }, 'Un titre de niveau 2, dimensionné en conséquence'),
  heading({ level: 2, size: 'h5' }, 'Un titre de niveau 2, dimensionné comme un h5'),
)

Ton

Trois degrés d’insistance, du contraste plein au gris lisible le plus discret.

Par défaut — la couleur dans laquelle le corps de texte est composé.

Atténué — texte secondaire, encore confortablement lisible.

Discret — libellés et métadonnées.

stack({ gap: 'xs' },
  text('Par défaut — la couleur dans laquelle le corps de texte est composé.'),
  text({ tone: 'muted' }, 'Atténué — texte secondaire, encore confortablement lisible.'),
  text({ tone: 'subtle' }, 'Discret — libellés et métadonnées.'),
)

Alignement

Début

Centre

Fin

stack({ gap: 'xs' },
  text({ align: 'start' }, 'Début'),
  text({ align: 'center' }, 'Centre'),
  text({ align: 'end' }, 'Fin'),
)

Troncature et limite de lignes

truncate coupe une seule ligne avec des points de suspension. lines limite plutôt à un nombre de lignes, ce que veut généralement le résumé d’une carte.

Une seule ligne qui continue bien au-delà de la largeur de son conteneur et se retrouve coupée par des points de suspension plutôt que de passer à la ligne.

Limité à deux lignes. Ce paragraphe continue un moment pour que la limite ait quelque chose à couper, puis continue encore un peu, au-delà du point où la troisième ligne aurait commencé.

stack({ gap: 'md' },
  card({ variant: 'flat' }, cardBody(
    text({ truncate: true }, 'Une seule ligne qui continue bien au-delà de la largeur de son conteneur et se retrouve coupée par des points de suspension plutôt que de passer à la ligne.'),
  )),
  card({ variant: 'flat' }, cardBody(
    text({ lines: 2, tone: 'muted' }, 'Limité à deux lignes. Ce paragraphe continue un moment pour que la limite ait quelque chose à couper, puis continue encore un peu, au-delà du point où la troisième ligne aurait commencé.'),
  )),
)

Code en ligne et touches

Lancez sitelo build ou appuyez sur ⌘ K pour rechercher.

text(
  'Lancez ', code('sitelo build'), ' ou appuyez sur ', kbd('⌘'), ' ', kbd('K'), ' pour rechercher.',
)

Les enfants sont rendus comme du HTML — c’est ce qui fait fonctionner l’imbrication partout dans cette bibliothèque, et code() ne fait pas exception. Un extrait contenant des balises réclame donc la prop text, qui les échappe :

<em>Bonjour</em> — text : affiché tel qu’écrit

Bonjour — enfants : interprétés comme du balisage

stack({ gap: 'sm' },
  text(code({ text: '<em>Bonjour</em>' }), ' — text : affiché tel qu’écrit'),
  text(code('<em>Bonjour</em>'), ' — enfants : interprétés comme du balisage'),
)

Les deux servent. text est pour un extrait de code, où une balise doit être lue et non construite. Les enfants sont pour une sortie déjà colorisée, où le balisage est le propos — un résultat de Prism ou de Shiki entre directement.

sitelo build --root docs

sitelo build

stack({ gap: 'sm' },
  text(code({ text: 'sitelo build --root docs' })),
  text(code('<span style="color: var(--su-primary-soft-fg)">sitelo</span> build')),
)

Composer

Text accepte des enfants, pas seulement une chaîne — liens, code et emphase s’y imbriquent comme ils le feraient en HTML.

Les pages sont des fonctions qui renvoient du HTML. Voyez le guide écrire des pages.

text({ variant: 'lead' },
  'Les pages sont des fonctions qui renvoient du ',
  code('HTML'),
  '. Voyez le guide ',
  link({ href: '/fr/docs/pages' }, 'écrire des pages'),
  '.',
)

Changer d’élément

as remplace l’élément sans changer l’apparence — pour un titre visuel qui ne doit pas apparaître dans le plan, ou un <span> au fil d’une ligne de texte.

Ressemble à un titre, c’est un div

Style de légende sur un paragraphe

stack({ gap: 'xs' },
  text({ variant: 'h4', as: 'div' }, 'Ressemble à un titre, c’est un div'),
  text({ variant: 'caption', as: 'p' }, 'Style de légende sur un paragraphe'),
)

Masqué visuellement

visuallyHidden() garde le contenu dans l’arbre d’accessibilité mais hors de l’écran — le libellé dont un lecteur d’écran a besoin là où les lecteurs voyants le tirent du contexte.

État du build : réussi — le dernier build a réussi il y a 4 minutes

text(
  'État du build : ',
  chip({ color: 'success', dot: true }, 'réussi'),
  visuallyHidden(' — le dernier build a réussi il y a 4 minutes'),
)

Props

Prop	Type	Défaut	Description
`variant`	`'h1'…'h6' \| 'lead' \| 'body' \| 'small' \| 'caption' \| 'overline'`	`'body'`	Taille, graisse et élément par défaut.
`tone`	`'default' \| 'muted' \| 'subtle'`	`'default'`	Le contraste que porte le texte.
`align`	`'start' \| 'center' \| 'end'`	`'start'`	Alignement du texte.
`truncate`	`boolean`	`false`	Une ligne, coupée par des points de suspension.
`lines`	`number`	—	Limiter à ce nombre de lignes.
`as`	`string`	—	Remplace l’élément que la variante aurait choisi.

heading() prend level (1–6) et un size facultatif ; tout le reste est identique.