Ícones

• Ícones disponíveis
• Instalação & configuração
  • Se o seu projeto usa uma configuração personalizada
• Registrando ícones
  • Como os ícones são carregados?
  • Adicionando ícones ao iconRegistry
• Exibindo ícones
  • Adicionando ícones às entradas
  • Usando ícones SVG personalizados
  • Usando o componente <FormKitIcon />
• Manipuladores de clique do ícone
• Usando bibliotecas de terceiros
  • Usando FontAwesome com um iconLoaderUrl personalizado
  • Um exemplo de iconLoader Heroicons

FormKit vem com mais de 130 ícones prontos para uso! Com exceção dos ícones de marcas (como YouTube, TikTok ou Visa), todos os ícones são originais e licenciados pelo MIT para uso gratuito em seu projeto. Você pode usar nossos ícones, adicionar os seus, ou facilmente conectar a um conjunto de ícones de terceiros.

Usar ícones em seu projeto é tão fácil quanto fornecer o nome do ícone desejado para uma das propriedades de ícone de um input.

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

É tão fácil! 🎉

Uma rápida demonstração de ícones em ação

Ícones disponíveis

O pacote @formkit/icons vem com mais de 130 ícones comuns para facilitar o início! Use a pesquisa abaixo para filtrar os ícones disponíveis:

Instalação & configuração

Para a maioria dos usuários não é necessária instalação para usar ícones (embora recomendamos adicionar seus ícones ao iconRegistry para melhor desempenho). O suporte a ícones é fornecido por meio de um plugin FormKit de primeira parte chamado createThemePlugin(). Este plugin é habilitado por padrão se você estiver usando o defaultConfig() do FormKit.

Ao usar o defaultConfig que vem com o FormKit, você pode usar várias opções de configuração de nível superior para personalizar sua experiência. Veja os documentos createThemePlugin na próxima seção para explicações expandidas de cada uma.

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

createApp(App).use(plugin, defaultConfig({
  ...
  icons: { heart: '<svg...' }, // permite definir ícones para uso sem busca remota
  iconLoaderUrl: (iconName) => `https://...`, // onde carregar ícones remotos
  iconLoader: (iconName) => {}, // função para controle mais direto do que a substituição de iconLoaderUrl
  ...
}).mount('#app')

Se o seu projeto usa uma configuração personalizada

Se o seu projeto não está usando o defaultConfig fornecido pelo FormKit, então você precisará instalar o createThemePlugin() na configuração do seu projeto FormKit:

• Importe createThemePlugin() do pacote @formkit/themes.
• Adicione createThemePlugin() ao array de plugins do seu projeto dentro da sua configuração FormKit.

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

// IMPORTANTE: Isso é apenas necessário para aplicativos que NÃO usam defaultConfig()
createApp(App).use(plugin, {
  ...
  plugins: [
    createThemePlugin()
  ]
  ...
}.mount('#app')

O createThemePlugin aceita 4 argumentos opcionais:

• theme: Uma representação em string de um nome de tema FormKit, por exemplo, 'genesis'. Quando fornecido, se um tema FormKit correspondente for encontrado, ele será carregado automaticamente via CDN.
• icons: Um objeto de ícones SVG para ser adicionado ao iconRegistry interno. As chaves são nomes de ícones e os valores são SVGs, por exemplo { heart: '<svg ...' }
• iconLoaderUrl: Uma função que recebe iconName e retorna uma URL onde os ícones podem ser carregados se não forem encontrados no iconRegistry. Veja o exemplo
• iconLoader: Uma função que recebe iconName e retorna uma Promise que resolve para um SVG (como uma string) ou undefined. Use isso quando você precisar de mais controle do que apenas substituir o iconLoaderUrl. Veja o exemplo

Uma vez que o plugin de tema está instalado em seu projeto, seus inputs FormKit terão props de ícones disponíveis para uso.

Registrando ícones

Como os ícones são carregados?

FormKit passa por 4 etapas ao tentar carregar um ícone. Eles são, em ordem:

1. Valor da prop SVG - Se o valor da prop é um SVG (por exemplo, prefix-icon="<svg ..."), então o SVG fornecido será usado.
2. O iconRegistry - Se o valor da prop é uma string que não é um SVG, então FormKit procurará o ícone em seu iconRegistry interno para uma chave correspondente.
3. As variáveis CSS do seu projeto - Se houver uma variável CSS que corresponda a --fk-icon-${yourIconName} definida em seu CSS, ela será carregada no iconRegistry. O valor da variável CSS deve ser um SVG codificado em base64 - não deve ser envolvido em aspas. É assim que FormKit envia ícones padrão para inputs em seus temas de primeira parte.
4. Via CDN - Se nenhum ícone correspondente puder ser encontrado em seu código, então uma solicitação será feita ao pacote @formkit/icons via CDN. Se um nome de ícone correspondente for encontrado, ele será usado. Você pode substituir onde os ícones remotos são carregados se quiser usar uma biblioteca de ícones de terceiros como fallback.

Como FormKit recorre a solicitações de CDN para ícones, você pode começar facilmente em um novo projeto fornecendo nomes de ícones suportados para as props de ícones de seu input e eles serão carregados para você automaticamente - nenhuma configuração adicional necessária! 🪄

SVGs carregados remotamente são adicionados ao iconRegistry interno na primeira vez que um ícone é buscado. Solicitações adicionais para o mesmo ícone serão armazenadas em cache até que um usuário recarregue seu aplicativo.

Adicionando ícones ao iconRegistry

CDNs mágicos são ótimos — mas para obter o melhor desempenho possível, você deve registrar localmente em seu projeto os ícones que sabe que usará. Você pode fazer isso adicionando ícones à sua configuração FormKit raiz. Os ícones de primeira parte do FormKit podem ser importados do pacote @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, // espalhe um grupo inteiro de ícones
    ethereum, // ou adicione ícones individuais
    thirdPartyIcon, // você pode importar qualquer ícone SVG
    formkit: `<svg ...` // ou defina o seu próprio
  }
  ...
}).mount('#app')

Exibindo ícones

Adicionando ícones às entradas

Muitas entradas do FormKit suportam ícones suffix e prefix. Você pode usar as props prefix-icon e suffix-icon em qualquer entrada do tipo text como text, email, search, date, etc. Essas props estão disponíveis nas entradas select, color, e range também.

A entrada select tem uma prop select-icon que permite alterar o ícone usado para o controle de entrada do select.

A entrada file tem props file-remove-icon e file-item-icon:

Usando ícones SVG personalizados

Às vezes, você precisa renderizar um ícone único em seu projeto. Você pode fornecer diretamente uma definição SVG para uma prop de ícone e o SVG será renderizado para você:

Usando o componente <FormKitIcon />

O FormKit vem com um componente chamado <FormKitIcon /> que permite exibir qualquer ícone do iconRegistry em qualquer lugar dentro do seu projeto. Precisa de um ícone que você está usando no FormKit em alguma outra parte da sua UI? Sem problemas:

Manipuladores de clique do ícone

Cada prop de ícone registra uma prop de manipulador de clique. Por exemplo, a prop prefix-icon terá uma prop correspondente @prefix-icon-click.

Cada prop de manipulador de clique recebe o núcleo node da entrada e o event de clique como argumentos.

Usando bibliotecas de terceiros

Se você deseja usar um conjunto de ícones de terceiros em seu projeto FormKit, você pode fornecer um iconLoaderUrl personalizado ou um iconLoader completo (globalmente, no nível de configuração do nó, ou como uma propriedade de componente) que é responsável por recuperar ícones que ainda não existem no iconRegistry.

Às vezes — em casos como um construtor de formulários ou CMS — você não sabe antecipadamente quais ícones precisará. É aí que o carregamento remoto de ícones brilha.

• As funções iconLoaderUrl e iconLoader recebem o atual iconName como argumento
• O valor de retorno de iconLoaderUrl deve ser uma URL para um CDN remoto onde o ícone SVG pode ser encontrado. Esta é a maneira mais fácil de alterar o comportamento de carregamento de fallback.
• se você precisar de mais controle, use iconLoader que permite a substituição de toda a lógica para busca remota de ícones. Esta função deve retornar uma Promise que resolve para string (o SVG) ou undefined.
• Você só precisa usar iconLoaderUrl ou iconLoader — se você fornecer ambos, então iconLoader tem precedência.

Usando FontAwesome com um iconLoaderUrl personalizado

Abaixo está uma implementação do FormKit carregando ícones do FontAwesome substituindo o iconLoaderUrl por um caminho CDN diferente.

Um exemplo de iconLoader Heroicons

Abaixo está uma implementação do FormKit com um iconLoader totalmente personalizado que busca ícones ausentes do Heroicons em vez do conjunto de ícones FormKit.