---
title: La Gaufre
sidebar:
  order: 30
---

import { Aside } from "@astrojs/starlight/components"
import assetGaufre from "./gaufre.png"
import { Code } from "@astrojs/starlight/components"
import gaufreHtml from "@gouvfr-lasuite/integration/dist/html/gaufre.html?raw"

![](./gaufre.png)

Le bouton "Gaufre" est un élément d'interface commun à tous les services de La Suite numérique. Il
permet aux internautes de facilement passer d'un service de La Suite à un autre.

Pour intégrer la Gaufre, il y a trois étapes :

- intégrer le HTML du bouton
- ajouter le fichier CSS nécessaire
- ajouter le fichier JS chargeant le widget au clic du bouton

:::note

Ce guide est à suivre pour intégrer la Gaufre sur toute page autre que
[votre page d'accueil](../homepage). Le gabarit de page d'accueil inclut déjà le bouton.

:::

## Règles d'utilisation

Le bouton Gaufre est destiné à être présent dans le coin supérieur droit de la page de votre page
web afin d'être toujours placé au même endroit quelque soit le service.

### Sur écran mobile/tablette

Sur petit écran, il est préférable d'afficher le bouton Gaufre en dehors d'un potentiel menu burger
existant, à gauche du menu burger :

![](./dsfr-gaufre.png)

Si pour quelconque raison ceci n'est pas possible, rajoutez un élément dans votre menu burger pour
accéder aux services de La Suite (voir section [bouton customisé](#bouton-customisé)).

## Installation

### 1. HTML

#### Avec React

Si vous utilisez React, utilisez le composant `Gaufre` fourni par le paquet :

```jsx
import { Gaufre } from "@gouvfr-lasuite/integration"

function MonComposant() {
  return <Gaufre />
}
```

Vous pouvez passer une prop `variant` au composant Gaufre pour changer l'affichage du bouton :

- `variant="responsive"` : le bouton s'affiche plus petit sur écran mobile/tablette
- `variant="small"` : le bouton s'affiche plus petit, tout le temps. **Ceci est la variante
  recommandée si vous utilisez une entête DSFR**.

:::note

Même en utilisant React, vous devrez charger le CSS et le JS manuellement. Ce petit travail
supplémentaire est fait pour vous donner plus de contrôle sur le chargement des assets suivant votre
stack technique.

:::

#### Sans React

Si vous n'utilisez pas React, utilisez le HTML présent dans le paquet :

<Code code={gaufreHtml} lang="html" title="@gouvfr-lasuite/integration/dist/html/gaufre.html" />

- ajouter une classe `lasuite-gaufre-btn--responsive` pour afficher le bouton plus petit sur écran
  mobile/tablette
- ajouter une classe `lasuite-gaufre-btn--small` pour afficher le bouton plus petit, tout le temps.
  **Ceci est recommandé si vous utilisez une entête DSFR**.

#### Dans une entête DSFR

Si vous intégrez le bouton Gaufre dans un projet suivant le DSFR :

- rajoutez le bouton en 1er enfant de `div.fr-header__navbar` pour que le bouton s'affiche à gauche
  du menu burger sur petit écran,
- puis en dernier élément de la liste `.fr-header__tools > .fr-header__tools-links > .fr-btns-group`
  pour que le bouton s'affiche en haut à droite de l'écran sur grand écran.

N'oubliez pas d'utiliser la classe `lasuite-gaufre-btn--small` pour que la taille du bouton
corresponde avec le reste de l'entête.

### 2. CSS

Le CSS nécessaire est présent dans `@gouvfr-lasuite/integration/dist/css/gaufre.css`. Il est à
inclure dans votre projet comme n'importe quel fichier CSS.

Suivant votre stack technique, vous pouvez peut-être inclure directement le CSS depuis les
dépendances. Par exemple avec _vite_ :

<Code
  code={`@import "@gouvfr-lasuite/integration/dist/css/gaufre.css";`}
  lang="css"
  title="vos/styles/globaux/app.css"
/>

Si vous n'utilisez pas de _bundler_ particulier et que avez plutôt décidé à l'installation de
[copier les assets](/guides/getting-started/#gestion-des-assets), vous pouvez inclure le CSS
directement via une balise `link` comme tout fichier CSS.

### 3. JS

Après avoir ajouté le bouton, il est nécessaire de le faire fonctionner. Pour ça, chargez ce fichier
JS externe qui s'occupe d'afficher le widget au clic du bouton. Vous pouvez ajouter ce code dans
votre `<head>` :

<Code
  code={`<script id="lasuite-gaufre-script" async defer src="${import.meta.env.PUBLIC_LASUITE_API_URL}/api/v1/gaufre.js"></script>`}
  lang="html"
/>

Si vous voulez afficher la liste des services de La Suite territoriale, remplacez `src` par :

<Code code={`${import.meta.env.PUBLIC_LASUITE_API_URL}/api/v1/gaufre.js?type=local`} lang="text" />

:::note

Pour que le script fonctionne il est nécessaire qu'il ait un id `lasuite-gaufre-script`. Ne
l'enlevez pas en copiant l'exemple !

:::

## Bouton customisé

Si vous ne voulez pas utiliser le bouton Gaufre standard, vous pouvez créer votre propre bouton avec
vos propres styles.

Cela est nécessaire si vous voulez par exemple avoir une ligne "Services de La Suite" dans un menu
burger : aucun HTML n'est proposé pour ça, tant il dépend de votre site.

- ⚠ pour que le bouton fonctionne, il doit avoir une classe `js-lasuite-gaufre-btn` pour que le
  JavaScript d'initialisation détecte votre bouton,
- parmi les classes CSS fournis, vous pouvez réutiliser `lasuite-gaufre-mask-element` ou
  `lasuite-gaufre-mask` qui appliquent l'icône de la Gaufre via un `mask-image` à l'instar des
  icones dans le DSFR,
- ℹ le bouton standard ne s'affiche que si le script de la Gaufre a réussi à charger. Pour avoir le
  même comportement sur votre propre implémentation, vous pouvez vous appuyer sur la présence de la
  classe `lasuite--gaufre-loaded` sur la balise `html`.

## Exemple

[La Gaufre : exemple HTML](/examples/gaufre/html).
