Icônes

• Icônes disponibles
• Installation & configuration
  • Si votre projet utilise une configuration personnalisée
• Enregistrement des icônes
  • Comment les icônes sont-elles chargées ?
  • Ajouter des icônes à iconRegistry
• Affichage des icônes
  • Ajouter des 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 une iconLoaderUrl personnalisée
  • 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 de 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 le démarrage ! Utilisez la recherche ci-dessous pour filtrer les icônes disponibles :

Installation & configuration

Pour la plupart des utilisateurs aucune installation n'est requise pour utiliser les icônes (bien que nous recommandons d'ajouter vos icônes à l'iconRegistry pour une meilleure performance). Le support des icônes est fourni via un plugin FormKit de première partie appelé createThemePlugin(). Ce plugin est activé par défaut si vous utilisez le defaultConfig() de FormKit.

Lors de l'utilisation du defaultConfig qui est livré avec FormKit, vous pouvez utiliser plusieurs options de configuration de haut niveau pour personnaliser votre expérience. Voir les documents createThemePlugin dans la section suivante pour des explications élargies de chacun.

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 à distance
  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 le defaultConfig fourni par FormKit, alors vous devrez installer le createThemePlugin() dans la configuration de votre projet FormKit :

• Importez createThemePlugin() depuis le package @formkit/themes.
• Ajoutez createThemePlugin() à l'array de plugins de votre projet à l'intérieur de votre configuration FormKit.

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

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

Le createThemePlugin prend 4 arguments optionnels :

• theme : Une représentation en chaîne de caractères d'un nom de 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 renvoie une URL où les icônes peuvent être chargées si elles ne sont pas trouvées dans le iconRegistry. Voir l'exemple
• iconLoader : Une fonction qui reçoit iconName et renvoie 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 l'exemple

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

Enregistrement des icônes

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

FormKit passe par 4 étapes lorsqu'il tente de charger une icône. Elles sont, dans l'ordre :

1. Valeur de la prop SVG - Si la valeur de la prop est un SVG (par exemple prefix-icon="<svg ..."), alors le SVG fourni sera utilisé.
2. Le iconRegistry - Si la valeur de la prop est une chaîne de caractères qui n'est pas un SVG, alors FormKit cherchera l'icône dans son iconRegistry interne pour une clé correspondante.
3. Les variables CSS de votre projet - S'il existe une variable CSS qui correspond à --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 expédie 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, alors une requête sera faite au package @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 secours.

Parce que FormKit retombe sur les requêtes CDN pour les icônes, vous pouvez facilement commencer dans un nouveau projet en fournissant des noms d'icônes supportés à vos props d'icônes d'entrée et ils seront chargés pour vous automatiquement - 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.

Ajouter des icônes à 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 package @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 le vôtre
  }
  ...
}).mount('#app')

Affichage des icônes

Ajouter des icônes aux entrées

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

L'entrée select a une prop 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 props file-remove-icon et file-item-icon :

Utilisation d'icônes SVG personnalisées

Parfois, vous devez rendre une icône unique dans votre projet. Vous pouvez fournir directement une définition SVG à une prop 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 d'afficher n'importe quelle icône de 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 prop d'icône enregistre une prop de gestionnaire de clic. Par exemple, la prop prefix-icon aura une prop correspondante @prefix-icon-click.

Chaque prop de gestionnaire de clic reçoit le node central de l'entrée et l'événement de clic event comme 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, ou en tant que prop 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 constructeur 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 à distance. Cette fonction doit renvoyer une Promise qui se résout en string (le SVG) ou undefined.
• Vous n'avez besoin d'utiliser iconLoaderUrl ou iconLoader — si vous fournissez les deux, alors iconLoader a la priorité.

Utilisation de FontAwesome avec une iconLoaderUrl personnalisée

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

Un exemple de iconLoader Heroicons

Ci-dessous se trouve 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.