sanity-plugin-iconify

Sanity Plugin Iconify

Custom input with over 150,000 open source vector icons

📒 Table of Contents

• 📒 Table of Contents
• 📍 Overview
• 🚀 Getting Started
  • Installation
  • Configuration
  • Add Icon schema type
• ✨ Usage
  • Options
    • collections
    • showName
  • Output
  • Preview
• 🤝 Contributing
• 🧪 Develop & test
• 👏 Acknowledgments
• 📄 License

📍 Overview

Enhance your Sanity project with the Iconify plugin, which introduces an Icon schema type and a custom input component. Leveraging the extensive library of open-source vector icons available through the Iconify, this plugin enables you to effortlessly select and integrate over 150,000 icons from popular icon sets directly into your Sanity project.

🚀 Getting Started

Requires Sanity Studio v5. For Sanity Studio v3/v4, use v2.x.

Installation

Install the plugin:

npm install sanity-plugin-iconify

yarn add sanity-plugin-iconify

pnpm add sanity-plugin-iconify

Configuration

Then add it as a plugin in sanity.config.ts (or .js):

import { defineConfig } from 'sanity';
import { iconify } from 'sanity-plugin-iconify';

export default defineConfig({
  //...
  plugins: [iconify({
    // Optional configuration

    // Filter icons by collection for all Icon fields (this field has typed autocomplete ✨)
    // Defaults to empty array (all collections)
    collections: ['fa-brands', 'mdi', ...],

    // Shows the selected icon name and collection underneath the icon picker
    // Defaults to false
    showName: false,
  })],
});

(Read more on configuration options here.)

Add Icon schema type

Use the Icon schema type in your Sanity schemas:

const type = defineType({
  type: 'document'
  name: 'myDocument',
  title: 'My Document',
  // ...
  fields: [
    // ...
    {
      name: 'myIcon',
      title: 'My Icon',
      type: 'icon', // <-- Icon schema type
    },
  ],
})

Learn more about Sanity schema types here.

✨ Usage

Options

collections

Filter icons by collection for all Icon fields. This option allows you to categorize icons based on predefined sets, making it easier to navigate and select from a curated list of icons. You can specify this field both in the plugin options and in the schema type options, with the latter overriding the plugin options. The package includes types for all collection prefixes, enabling typed autocomplete for this field.

Default: [] (all collections)

import { defineConfig } from 'sanity';

export default defineConfig({
  //...
  plugins: [iconify({
    collections: ['fa-brands', 'mdi', ...], // <-- Filter icons by collection for all Icon fields
  })],
});

const type = defineType({
  type: 'document'
  name: 'myDocument',
  title: 'My Document',
  // ...
  fields: [
    // ...
    {
      name: 'myIcon',
      title: 'My Icon',
      type: 'icon',
      options: {
        collections: ['fa-brands', 'mdi', ...], // <-- Filter icons by collection for this field
      },
    },
  ],
})

showName

Enables the display of the selected icon's name and collection underneath the icon picker, providing a quick reference and ease of identification. This field can be specified in both the plugin options and the schema type options, with the schema type options having priority over the plugin options.

Default: false

import { defineConfig } from 'sanity';

export default defineConfig({
  //...
  plugins: [
    iconify({
      showName: true, // <-- Shows the selected icon name and collection underneath all icon pickers
    }),
  ],
});

const type = defineType({
  type: 'document'
  name: 'myDocument',
  title: 'My Document',
  // ...
  fields: [
    // ...
    {
      name: 'myIcon',
      title: 'My Icon',
      type: 'icon',
      options: {
        showName: true, // <-- Shows the selected icon name and collection underneath this icon picker
      },
    },
  ],
})

Output

The Icon schema type outputs an object with the icon name.

{
  _type: 'icon',
  name: string; // The iconify name of the icon
}

This name can be utilized in your frontend to render the icon dynamically. For instance, using React Iconify allows you to render the icon as demonstrated below:

import { Icon } from '@iconify/react';

<Icon icon={icon.name} />;

This will render an SVG on demand, which looks great and is very performant. There are also libraries/API's for:

• Vue
• Svelte
• Astro
• And more (Plain SVGs, Tailwind, Web Components, etc.)

For further information, you may refer to the official documentation.

Preview

The plugin includes a custom list preview that automatically renders the selected icon accompanied by its name and collection.

If needed you can override this preview component by specifying your own in the schema type options. Use the @iconify/react package to render the icon.

import { Icon } from '@iconify/react';
import { defineType } from 'sanity';

const type = defineType({
  type: 'array'
  name: 'myArray',
  title: 'My array of icons',
  of: [
    {
      type: 'icon',
      components: {
        preview: (props: PreviewProps) => {
          return props.renderDefault({
            ...props,
            title: 'Custom title',
            subtitle: 'Custom subtitle',
            media: <Icon icon={props.title as string} />, // <-- Renders the selected icon as media
          });
        },
      },
    },
  ],
})

Learn more about Sanity previews here.

🤝 Contributing

Contributions, whether in the form of code enhancements, bug fixes, documentation, or design improvements, are always welcome! Here are the steps to get started:

• Fork the project repository. This creates a copy of the project on your account that you can modify without affecting the original project.
• Clone the forked repository to your local machine using a Git client like Git or GitHub Desktop.
• Create a new branch with a descriptive name (e.g., new-feature-branch or bugfix-issue-123).

git checkout -b new-feature-branch

• Make changes to the project's codebase.
• Commit your changes to your local branch with a clear conventional commit message that explains the changes you've made.

git commit -m 'feat: Implemented new feature.'

• Push your changes to your forked repository on GitHub using the following command

git push origin new-feature-branch

• Create a new pull request to the original project repository. In the pull request, describe the changes you've made and why they are necessary. Make sure to update or add documentation as relevant. I will review your changes, provide feedback, or merge them into the main branch.

🧪 Develop & test

This plugin uses @sanity/plugin-kit with default configuration for build & watch scripts.

See Testing a plugin in Sanity Studio on how to run this plugin with hotreload in the studio.

👏 Acknowledgments

• sanity-plugin-icon-picker - is a solid alternative built around react-icons.

📄 License

MIT © Wannes Salomé