Icônes

• Icônes disponibles
• Installation et configuration
  • Si votre projet utilise une configuration personnalisée
• Enregistrement des icônes
  • Comment les icônes sont-elles chargées ?
  • Ajout d'icônes à l'iconRegistry
• Affichage des icônes
  • Ajout d'icônes aux entrées
  • Utilisation d'icônes SVG personnalisées
  • Utilisation du composant <FormKitIcon />
• Gestionnaires de clic d'icône
• Utilisation de bibliothèques tierces
  • Utilisation de FontAwesome avec un iconLoaderUrl personnalisé
  • Un exemple de iconLoader Heroicons

FormKit est livré avec plus de 130 icônes prêtes à l'emploi ! À l'exception des icônes de marque (comme YouTube, TikTok ou Visa), toutes les icônes sont originales et sous licence MIT pour une utilisation gratuite dans votre projet. Vous pouvez utiliser nos icônes, ajouter les vôtres, ou facilement vous connecter à un ensemble d'icônes tiers.

Utiliser des icônes dans votre projet est aussi simple que de fournir le nom de l'icône souhaitée à l'une des propriétés d'icône d'une entrée.

<FormKit prefix-icon="email" />
<FormKit suffix-icon="settings" />
<FormKit type="select" select-icon="caretDown" />

C'est aussi simple que ça ! 🎉

Une démonstration rapide des icônes en action

Icônes disponibles

Le paquet @formkit/icons est livré avec plus de 130 icônes courantes pour faciliter la prise en main ! Utilisez la recherche ci-dessous pour filtrer les icônes disponibles :

Installation et configuration

Pour la plupart des utilisateurs, aucune installation n'est requise pour utiliser les icônes (bien que nous recommandions d'ajouter vos icônes au iconRegistry pour de meilleures performances). La prise en charge des icônes est fournie via un plugin FormKit tiers appelé createThemePlugin() — Ce plugin est activé par défaut si vous utilisez la defaultConfig() de FormKit.

Lors de l'utilisation de la defaultConfig fournie avec FormKit, plusieurs options de configuration de haut niveau sont disponibles pour personnaliser votre expérience. Consultez les documents createThemePlugin dans la section suivante pour des explications détaillées de chacune.

import { createApp } from 'vue'
import App from 'App.vue'
import { plugin, defaultConfig } from '@formkit/vue'

createApp(App).use(plugin, defaultConfig({
  ...
  icons: { heart: '<svg...' }, // permet de définir des icônes pour une utilisation sans récupération à distance
  iconLoaderUrl: (iconName) => `https://...`, // où charger les icônes distantes
  iconLoader: (iconName) => {}, // fonction pour un contrôle plus direct que le remplacement de iconLoaderUrl
  ...
}).mount('#app')

Si votre projet utilise une configuration personnalisée

Si votre projet n'utilise pas la defaultConfig fournie par FormKit, vous devrez installer le createThemePlugin() dans la configuration de votre projet FormKit :

• Importez createThemePlugin() depuis le paquet @formkit/themes.
• Ajoutez createThemePlugin() au tableau de plugins de votre projet dans votre configuration FormKit.

import { createApp } from 'vue'
import App from 'App.vue'
import { createThemePlugin } from '@formkit/themes'
import { plugin } from '@formkit/vue'

// IMPORTANT : Ceci est uniquement nécessaire pour les applications qui n'utilisent PAS defaultConfig()
createApp(App).use(plugin, {
  ...
  plugins: [
    createThemePlugin()
  ]
  ...
}.mount('#app')

Le createThemePlugin prend 4 arguments facultatifs :

• theme : Une chaîne de caractères représentant le nom d'un thème FormKit, par exemple 'genesis'. Lorsqu'il est fourni, si un thème FormKit correspondant est trouvé, il sera chargé automatiquement via CDN.
• icons : Un objet d'icônes SVG à ajouter au iconRegistry interne. Les clés sont les noms des icônes et les valeurs sont les SVG, par exemple { heart: '<svg ...' }
• iconLoaderUrl : Une fonction qui reçoit iconName et retourne une URL où les icônes peuvent être chargées si elles ne sont pas trouvées dans le iconRegistry. Voir exemple
• iconLoader : Une fonction qui reçoit iconName et retourne une promesse qui se résout en un SVG (sous forme de chaîne) ou undefined. Utilisez ceci lorsque vous avez besoin de plus de contrôle que simplement remplacer le iconLoaderUrl. Voir exemple

Une fois le plugin de thème installé dans votre projet, vos entrées FormKit auront des propriétés d'icônes disponibles à utiliser.

Enregistrement des icônes

Comment les icônes sont-elles chargées ?

FormKit suit 4 étapes pour charger une icône. Elles sont, dans l'ordre :

1. Valeur de la propriété SVG - Si la valeur de la propriété est un SVG (par exemple prefix-icon="<svg ..."), alors le SVG fourni sera utilisé.
2. Le iconRegistry - Si la valeur de la propriété est une chaîne de caractères qui n'est pas un SVG, FormKit recherchera l'icône dans son iconRegistry interne pour une clé correspondante.
3. Les variables CSS de votre projet - S'il existe une variable CSS correspondant à --fk-icon-${yourIconName} définie dans votre CSS, elle sera chargée dans le iconRegistry. La valeur de la variable CSS doit être un SVG encodé en base64 — elle ne doit pas être entourée de guillemets. C'est ainsi que FormKit fournit les icônes par défaut pour les entrées dans ses thèmes de première partie.
4. Via CDN - Si aucune icône correspondante ne peut être trouvée dans votre base de code, une requête sera faite au paquet @formkit/icons via CDN. Si un nom d'icône correspondant est trouvé, il sera utilisé. Vous pouvez remplacer l'endroit où les icônes distantes sont chargées si vous souhaitez utiliser une bibliothèque d'icônes tierce en tant que solution de repli.

Comme FormKit utilise les requêtes CDN pour les icônes, vous pouvez facilement commencer dans un nouveau projet en fournissant des noms d'icônes pris en charge pour les propriétés d'icônes de votre entrée et elles seront chargées automatiquement pour vous — aucune configuration supplémentaire requise ! 🪄

Les SVG chargés à distance sont ajoutés au iconRegistry interne la première fois qu'une icône est récupérée. Les demandes supplémentaires pour la même icône seront mises en cache jusqu'à ce qu'un utilisateur recharge votre application.

Ajout d'icônes à l'iconRegistry

Les CDN magiques sont géniaux — mais pour obtenir les meilleures performances possibles, vous devriez enregistrer localement dans votre projet les icônes que vous savez que vous allez utiliser. Vous pouvez le faire en ajoutant des icônes à votre configuration FormKit racine. Les icônes de première partie de FormKit peuvent être importées à partir du paquet @formkit/icons.

yarn add @formkit/icons

import { createApp } from 'vue'
import App from 'App.vue'
import { applicationIcons, ethereum } from '@formkit/icons'
import { thirdPartyIcon } from '@some-other-icon-package'
import { plugin, defaultConfig } from '@formkit/vue'

createApp(App).use(plugin, defaultConfig({
  ...
  icons: {
    ...applicationIcons, // étendre un groupe entier d'icônes
    ethereum, // ou ajouter des icônes individuelles
    thirdPartyIcon, // vous pouvez importer n'importe quelle icône SVG
    formkit: `<svg ...` // ou définir la vôtre
  }
  ...
}).mount('#app')

Affichage des icônes

Ajout d'icônes aux entrées

De nombreuses entrées FormKit prennent en charge les icônes suffix et prefix. Vous pouvez utiliser les propriétés prefix-icon et suffix-icon sur n'importe entrée de type text comme text, email, search, date, etc. Ces propriétés sont également disponibles sur les entrées select, color, et range.

L'entrée select a une propriété select-icon qui vous permet de changer l'icône utilisée pour le contrôle de l'entrée de sélection.

L'entrée file a des propriétés file-remove-icon et file-item-icon :

Utilisation d'icônes SVG personnalisées

Parfois, vous devez afficher une icône unique dans votre projet. Vous pouvez fournir directement une définition SVG à une propriété d'icône et le SVG sera rendu pour vous :

Utilisation du composant <FormKitIcon />

FormKit est livré avec un composant appelé <FormKitIcon /> qui vous permet de générer n'importe quelle icône du iconRegistry n'importe où dans votre projet. Besoin d'une icône que vous utilisez dans FormKit sur une autre partie de votre interface utilisateur ? Pas de problème :

Gestionnaires de clic d'icône

Chaque propriété d'icône enregistre une propriété de gestionnaire de clic. La propriété prefix-icon aura une propriété correspondante @prefix-icon-click, etc.

Chaque propriété de gestionnaire de clic reçoit le node principal de l'entrée et l'événement click en arguments.

Utilisation de bibliothèques tierces

Si vous souhaitez utiliser un ensemble d'icônes tiers dans votre projet FormKit, vous pouvez fournir une iconLoaderUrl personnalisée ou un iconLoader complet (soit globalement, au niveau de la configuration du nœud, soit en tant que propriété de composant) qui est responsable de la récupération des icônes qui n'existent pas déjà dans le iconRegistry.

Parfois — dans des cas tels qu'un générateur de formulaires ou un CMS — vous ne savez pas à l'avance quelles icônes vous aurez besoin. C'est là que le chargement à distance des icônes brille.

• Les fonctions iconLoaderUrl et iconLoader reçoivent chacune le iconName actuel en argument
• La valeur de retour de iconLoaderUrl doit être une URL vers un CDN distant où l'icône SVG peut être trouvée. C'est le moyen le plus simple de modifier le comportement de chargement de secours.
• si vous avez besoin de plus de contrôle, utilisez iconLoader qui permet de remplacer toute la logique de récupération d'icônes distantes. Cette fonction doit renvoyer une Promise qui se résout en string (le SVG) ou undefined.
• Vous avez seulement besoin d'utiliser iconLoaderUrl ou iconLoader — si vous fournissez les deux, alors iconLoader prend le dessus.

Utilisation de FontAwesome avec un iconLoaderUrl personnalisé

Ci-dessous, une implémentation de FormKit chargeant des icônes de FontAwesome en remplaçant le iconLoaderUrl par un chemin CDN différent.

Un exemple de iconLoader Heroicons

Ci-dessous, une implémentation de FormKit avec un iconLoader entièrement personnalisé qui récupère les icônes manquantes de Heroicons au lieu de l'ensemble d'icônes FormKit.