Personnaliser l’affichage d’un widget avec du CSS

STUDIO WIDGETS

Le Studio Widgets permet d’ajouter du CSS personnalisé afin d’adapter l’apparence d’un widget à son contexte d’intégration. Ce champ peut être utilisé pour ajuster la présentation des résultats, améliorer la lisibilité, harmoniser le rendu avec un site ou appliquer des corrections visuelles ponctuelles.

Pourquoi utiliser du CSS personnalisé ?

Les widgets disposent déjà de nombreux paramètres de configuration dans le Studio : choix du modèle d’affichage, champs visibles, filtres, carte, options de présentation ou encore contenus affichés.

Dans certains cas, ces réglages ne suffisent pas à obtenir un rendu parfaitement adapté à la page d’intégration. Le CSS personnalisé permet alors d’ajouter une couche d’ajustement visuel, sans modifier les données affichées ni le fonctionnement du widget.

Adapter le rendu au contexte

Ajuster l’affichage selon la largeur disponible, la structure de la page ou le type de contenu intégré.

Améliorer l’expérience utilisateur

Rendre la lecture plus confortable, faciliter la consultation des résultats ou éviter certains effets visuels gênants.

Harmoniser avec le site hôte

Adapter certains éléments graphiques pour que le widget s’intègre mieux à l’environnement dans lequel il est affiché.

Bon à savoir : le CSS personnalisé agit uniquement sur l’apparence du widget. Il ne modifie ni les offres affichées, ni les critères de sélection, ni les paramètres fonctionnels du widget.

Où ajouter du CSS personnalisé ?

Le champ dédié au CSS personnalisé est disponible dans le Studio Widgets, depuis la configuration du widget.

Ouvrir le widget concerné dans le Studio.
Accéder à la rubrique Avancé.
Repérer le champ Code CSS personnalisé.
Ajouter les règles CSS souhaitées.
Enregistrer le widget.
Tester le rendu sur la page du site où le widget est intégré.

Conseil : après chaque modification, vérifiez le rendu sur plusieurs largeurs d’écran : ordinateur, tablette et mobile.

Précautions avant d’ajouter du CSS

Le CSS personnalisé est utile pour répondre à des besoins d’affichage précis, mais il doit être utilisé avec prudence. Une règle trop générale peut modifier plusieurs zones du widget, parfois au-delà de l’effet recherché.

Bonne pratique	Pourquoi ?
Tester le widget sur plusieurs tailles d’écran	Un affichage satisfaisant sur ordinateur peut être moins lisible sur mobile.
Limiter les règles trop globales	Une règle appliquée à une classe générique peut modifier plusieurs parties du widget.
Si du CSS personnalisé était déjà présent, conserver une copie de celui-ci avant de le modifier dans le Studio	Cela permet de revenir rapidement à une version précédente si nécessaire.
Éviter de masquer des informations essentielles	Le CSS ne doit pas nuire à la compréhension des offres ou à l’accessibilité du widget.

Attention : les codes proposés dans cet article sont des bases d’adaptation. Selon le modèle de widget utilisé, la largeur du site hôte ou les styles déjà présents sur la page, des ajustements peuvent être nécessaires.

Afficher les résultats sur deux colonnes

Sur certains modèles, notamment les affichages de type Liste + carte, les cartes peuvent occuper toute la largeur disponible. Cela peut donner une impression de mise en avant excessive du premier résultat ou rendre la liste moins agréable à lire.

Le code ci-dessous permet de présenter les résultats sur deux colonnes lorsque la largeur disponible le permet.

/* Grille de résultats */
.list-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(250px, 1fr)) !important;
  gap: 20px;
}

/* Évite les cartes trop étroites */
.list-card,
.list-card-image-wrapper {
  max-width: 100% !important;
}

/* Liste avec carte */
.widget-content:has(> [slot="map"]) [slot="list"] .list-grid {
  grid-template-columns: repeat(2, 1fr) !important;
}

/* Agenda avec carte */
.widget-content:has(> [slot="map"]) [slot="agenda"] .list-grid {
  grid-template-columns: repeat(2, 1fr) !important;
}

/* Liste avec filtres */
.widget-content:has(> [slot="filters"]) [slot="list"] .list-grid {
  grid-template-columns: repeat(2, 1fr) !important;
}

/* Agenda avec filtres */
.widget-content:has(> [slot="filters"]) [slot="agenda"] .list-grid {
  grid-template-columns: repeat(2, 1fr) !important;
}

/* Adaptation responsive */
@media (max-width: 1200px) {
  .list-grid {
    grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)) !important;
  }
}

Dans quel cas utiliser ce code ? Ce type d’ajustement est utile lorsque les cartes de résultats paraissent trop grandes ou lorsqu’un affichage sur deux colonnes améliore la lecture de la liste.

Réduire la hauteur des images

Lorsque les visuels prennent beaucoup de place dans les cartes, il est possible de limiter leur hauteur. Cela permet de faire remonter plus rapidement les informations importantes : titre, commune, type d’objet ou autre.

.list-card-image-wrapper {
  min-height: auto !important;
  height: 160px !important;
  overflow: hidden;
}

.list-card-image-wrapper img {
  width: 100%;
  height: 100%;
  object-fit: cover;
}

À adapter : la valeur 160px peut être augmentée ou réduite selon le rendu souhaité et la place disponible dans la page.

Afficher les résultats sous forme de liste compacte responsive

Pour certains usages, un affichage plus compact peut être préférable à une grille de grandes cartes. Le code ci-dessous permet d’obtenir un rendu de type liste, avec l’image à gauche et les informations à droite.

Avant :

Après :

Le code adapte également le comportement selon le contexte : si le widget contient une carte, les résultats restent affichés en liste verticale. Si le widget ne contient pas de carte, les résultats peuvent s’afficher sur deux ou trois colonnes selon la largeur disponible.

/* =========================================================
   WIDGET — Liste compacte responsive
   Objectif :
   - avec carte : résultats en liste verticale
   - sans carte : résultats en 2 ou 3 colonnes selon la largeur
   ========================================================= */


/* =========================
   BASE : affichage sans carte
   ========================= */

.list-grid {
  display: grid !important;
  grid-template-columns: repeat(auto-fit, minmax(360px, 1fr)) !important;
  gap: 22px !important;
  align-items: start;
}

/* Les cartes doivent pouvoir prendre toute la largeur de leur colonne */
apidae-list-item-card {
  display: block !important;
  width: 100% !important;
  min-width: 0 !important;
}


/* =========================
   CARTE EN FORMAT HORIZONTAL
   ========================= */

.list-card {
  display: grid !important;
  grid-template-columns: 170px minmax(0, 1fr) !important;
  gap: 18px !important;
  align-items: stretch !important;

  width: 100% !important;
  max-width: none !important;
  min-width: 0 !important;
  min-height: auto !important;
  max-height: none !important;
}

.list-card-image-wrapper {
  width: 170px !important;
  min-width: 170px !important;
  height: 130px !important;
  overflow: hidden !important;
  max-width: none !important;
  min-height: 140px !important;
}

.list-card-image-wrapper img {
  width: 100% !important;
  height: 100% !important;
  object-fit: cover !important;
}

.list-card-text {
  min-width: 0 !important;
      max-width: 100%;
}

.list-card-title {
  margin-top: 0 !important;
}


/* =========================
   CAS AVEC CARTE
   Quand le widget contient une carte, on repasse la liste en une colonne.
   ========================= */

.widget-content:has(> [slot="map"]) [slot="list"] .list-grid {
  display: flex !important;
  flex-direction: column !important;
  gap: 18px !important;
}


/* =========================
   RESPONSIVE
   ========================= */

@media (max-width: 900px) {
  .list-grid {
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)) !important;
  }

  .list-card {
    grid-template-columns: 150px minmax(0, 1fr) !important;
  }

  .list-card-image-wrapper {
    width: 150px !important;
    min-width: 150px !important;
    height: 120px !important;
  }
}

@media (max-width: 700px) {
  .list-grid {
    grid-template-columns: 1fr !important;
  }

  .list-card {
    display: block !important;
  }

  .list-card-image-wrapper {
    width: 100% !important;
    min-width: 0 !important;
    height: 180px !important;
  }
}

Attention : cette personnalisation modifie fortement la structure visuelle des résultats. Elle doit être testée attentivement, notamment sur mobile, sur les widgets avec carte et sur les widgets contenant beaucoup d’informations.

Rendre le bouton d’ouverture des filtres plus visible

Les filtres sont actuellement masqués au chargement de la page afin de gagner de la place pour la carte et l'affichage des offres. Leur ouverture se fait alors depuis le bouton représenté par une icône dans l’en-tête du widget :

Selon le contexte d’intégration, ce bouton peut ne pas être suffisamment visible ou explicite pour les visiteurs. En attendant une solution plus adaptée et permanente dans le Studio Widgets, il est possible d’améliorer son affichage avec du CSS personnalisé.

Le code ci-dessous permet d’ajouter un libellé au bouton des filtres et d’harmoniser son comportement visuel avec les autres boutons du widget : état fermé, survol et état ouvert.

/* =========================================================
   WIDGET — Bouton filtres plus explicite
   États :
   - fermé : gris
   - survol : couleur principale
   - ouvert : couleur principale
   ========================================================= */


/* =========================
   BOUTON FILTRES — BASE
   ========================= */

.filters-button {
  width: auto !important;
  display: inline-flex !important;
  align-items: center !important;
  gap: 8px !important;

  padding: 6px 12px !important;
  border: none !important;
  border-radius: 24px !important;

  background: transparent !important;
  color: #AAB4C3 !important;

  font-size: 16px !important;
  font-weight: 400 !important;
  font-family: var(--widget-text-font-family, inherit) !important;
  line-height: 1 !important;
  white-space: nowrap !important;

  cursor: pointer !important;
  transition: 0.2s ease !important;
}


/* =========================
   MASQUER L’ICÔNE NATIVE
   ========================= */

.filters-button apidae-icon[name="bold/settings_fine_tuning/tuning_2"] {
  display: none !important;
}

.filters-button .filters-button-icon-wrap,
.filters-button .filters-button-icon-wrap--active {
  display: none !important;
}


/* =========================
   ICÔNE CSS RECRÉÉE
   ========================= */

.filters-button::before {
  content: "";
  width: 20px;
  height: 20px;
  flex: 0 0 20px;

  background-color: currentColor;

  -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='black' d='M9.25 14C10.9069 14 12.25 15.3431 12.25 17C12.25 18.6569 10.9069 20 9.25 20C7.59315 20 6.25 18.6569 6.25 17C6.25 15.3431 7.59315 14 9.25 14Z'/%3E%3Cpath fill='black' d='M14.25 4C12.5931 4 11.25 5.34315 11.25 7C11.25 8.65685 12.5931 10 14.25 10C15.9069 10 17.25 8.65685 17.25 7C17.25 5.34315 15.9069 4 14.25 4Z'/%3E%3Cpath fill='black' d='M8.75 6.20852C9.16421 6.20852 9.5 6.54431 9.5 6.95852C9.5 7.37273 9.16421 7.70852 8.75 7.70852H1.75C1.33579 7.70852 1 7.37273 1 6.95852C1 6.54431 1.33579 6.20852 1.75 6.20852H8.75Z'/%3E%3Cpath fill='black' d='M14.75 16.2085C14.3358 16.2085 14 16.5443 14 16.9585C14 17.3727 14.3358 17.7085 14.75 17.7085H21.75C22.1642 17.7085 22.5 17.3727 22.5 16.9585C22.5 16.5443 22.1642 16.2085 21.75 16.2085H14.75Z'/%3E%3Cpath fill='black' d='M1 16.9585C1 16.5443 1.33579 16.2085 1.75 16.2085H3.75C4.16421 16.2085 4.5 16.5443 4.5 16.9585C4.5 17.3727 4.16421 17.7085 3.75 17.7085H1.75C1.33579 17.7085 1 17.3727 1 16.9585Z'/%3E%3Cpath fill='black' d='M21.75 6.20852C22.1642 6.20852 22.5 6.54431 22.5 6.95852C22.5 7.37273 22.1642 7.70852 21.75 7.70852H19.75C19.3358 7.70852 19 7.37273 19 6.95852C19 6.54431 19.3358 6.20852 19.75 6.20852H21.75Z'/%3E%3C/svg%3E");
  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='black' d='M9.25 14C10.9069 14 12.25 15.3431 12.25 17C12.25 18.6569 10.9069 20 9.25 20C7.59315 20 6.25 18.6569 6.25 17C6.25 15.3431 7.59315 14 9.25 14Z'/%3E%3Cpath fill='black' d='M14.25 4C12.5931 4 11.25 5.34315 11.25 7C11.25 8.65685 12.5931 10 14.25 10C15.9069 10 17.25 8.65685 17.25 7C17.25 5.34315 15.9069 4 14.25 4Z'/%3E%3Cpath fill='black' d='M8.75 6.20852C9.16421 6.20852 9.5 6.54431 9.5 6.95852C9.5 7.37273 9.16421 7.70852 8.75 7.70852H1.75C1.33579 7.70852 1 7.37273 1 6.95852C1 6.54431 1.33579 6.20852 1.75 6.20852H8.75Z'/%3E%3Cpath fill='black' d='M14.75 16.2085C14.3358 16.2085 14 16.5443 14 16.9585C14 17.3727 14.3358 17.7085 14.75 17.7085H21.75C22.1642 17.7085 22.5 17.3727 22.5 16.9585C22.5 16.5443 22.1642 16.2085 21.75 16.2085H14.75Z'/%3E%3Cpath fill='black' d='M1 16.9585C1 16.5443 1.33579 16.2085 1.75 16.2085H3.75C4.16421 16.2085 4.5 16.5443 4.5 16.9585C4.5 17.3727 4.16421 17.7085 3.75 17.7085H1.75C1.33579 17.7085 1 17.3727 1 16.9585Z'/%3E%3Cpath fill='black' d='M21.75 6.20852C22.1642 6.20852 22.5 6.54431 22.5 6.95852C22.5 7.37273 22.1642 7.70852 21.75 7.70852H19.75C19.3358 7.70852 19 7.37273 19 6.95852C19 6.54431 19.3358 6.20852 19.75 6.20852H21.75Z'/%3E%3C/svg%3E");

  -webkit-mask-repeat: no-repeat;
  mask-repeat: no-repeat;

  -webkit-mask-position: center;
  mask-position: center;

  -webkit-mask-size: contain;
  mask-size: contain;
}


/* =========================
   TEXTE AJOUTÉ
   ========================= */

.filters-button::after {
  content: "Filtrer";
  color: currentColor !important;
  font-size: 16px;
  font-weight: 400;
  line-height: 1;
}


/* =========================
   SURVOL — BOUTON FERMÉ
   ========================= */

.filters-button:not(.filters-button--active):hover {
  background: rgba(170, 180, 195, 0.2) !important;
  color: var(--widget-primary-color) !important;
}


/* =========================
   ÉTAT OUVERT
   ========================= */

.filters-button.filters-button--active {
  background: var(--widget-primary-color-rgba-20) !important;
  color: var(--widget-primary-color) !important;
}

.filters-button.filters-button--active::after {
  content: "Filtres";
  font-weight: 600;
}

A noter : cette personnalisation ne force pas l’ouverture des filtres au chargement du widget. Elle permet uniquement de rendre le bouton d’ouverture plus explicite et plus visible pour ceux qui le souhaitent.

Tester le rendu après intégration

Le rendu final d’un widget dépend aussi de la page dans laquelle il est intégré : largeur de la zone de contenu, marges, colonnes, thème graphique ou styles déjà présents sur le site.

Il est donc possible qu’un widget ne s’affiche pas exactement de la même manière dans l’aperçu du Studio et sur le site final.

Points à vérifier

Le nombre de résultats visibles à l’écran est satisfaisant.
Les titres et informations principales restent lisibles.
Les images ne sont pas déformées.
Les filtres, la carte et les boutons restent accessibles.
Le rendu reste confortable sur mobile.

Ce que le CSS personnalisé ne permet pas de faire

Le CSS personnalisé sert à ajuster l’apparence du widget. Il ne permet pas de modifier son fonctionnement métier ni les données retournées.

Possible avec du CSS	Non géré par le CSS
Modifier la taille des cartes ou des images	Changer les offres retournées par le widget
Adapter le nombre de colonnes	Modifier les critères de recherche ou de sélection
Ajuster les espacements et certains styles visuels	Ajouter de nouvelles fonctionnalités au widget
Améliorer le rendu responsive	Modifier le comportement natif de la carte, des filtres ou du moteur de recherche

À retenir

Le CSS personnalisé se renseigne depuis la rubrique Avancé du Studio Widgets.
Il permet d’adapter l’apparence du widget : présentation des résultats, images, colonnes, espacements ou rendu responsive.
Les règles ajoutées doivent être testées sur le site final et sur plusieurs tailles d’écran.
Le CSS ne modifie pas les données, les sélections ou le comportement métier du widget.