sanity-plugin-icon-manager

v1.4.0

Published

2 months ago

A Sanity plugin for selecting, managing, and customizing icons.

Downloads

140

0High
0Medium
0Low

williamiommi

sanity sanity-plugin sanity-plugin-icon-manager

Sanity Icon Manager

A Sanity plugin for selecting, managing, and customizing icons. Inspired by sanity-plugin-icon-picker.
Powered by Iconify

⚡️ Features

Sanity v3 plugin
Customizable icons
SVG code stored in Sanity
Media preview component for your entry
Download or copy to clipboard your icon
Presence and Change Indicator preserved
Custom Diff View
Provide your own color palette for monochrome icons
Basic API Hosting
v1.1.0+: Search filter 'Collection'
v1.2.0+: Collections tab
v1.3.0+: Global 'inline-svg' option
v1.4.0+: Limit Collections option

🔌 Installation

npm install sanity-plugin-icon-manager

🧑‍💻 Usage

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

import {defineConfig} from 'sanity'
import {IconManager} from 'sanity-plugin-icon-manager'

export default defineConfig({
  //...
  plugins: [
    IconManager({
      // your optional configuration here
    }),
  ],
  // ...
})

The plugin introduces one new object type called: icon.manager. You can define a new field with this type inside your documents.

import {defineField, defineType} from 'sanity'

const SampleDocument = defineType({
  type: 'document',
  name: 'sampleDocument',
  title: 'Sample Document',
  fields: [
    // ...
    defineField({
      type: 'icon.manager',
      name: 'icon',
      title: 'Icon',
    }),
    // ...
  ],
})

export default SampleDocument

⚙️ Plugin Configuration

This is the main configuration of the plugin. The available options are:

{
  // An array of strings containing a subset of collection IDs (e.g., ['ant-design', 'material-']). This can be used when you want to limit access to only specific collections. It utilizes the 'prefixes' query parameter available on the Iconify API. More information can be found here (https://iconify.design/docs/api/collections.html).
  availableCollections?: string[]
  // When set to true, this global option allows you to automatically store the inline version of the selected icon. This means that the 'Inline Svg' checkbox will be preselected by default when you choose a new icon.
  inlineSvg?: boolean

  // This is the endpoint if you decide to host your icon sets on your own server. For more details, see the dedicated session below
  customEndpoint?: string

  // an optional array of custom color palette
  customPalette?: [
    {
      hex: string, // the hex code of your custom color
      title?: string // an optional title for you custom color used as a tooltip inside the color picker.
    },
    // other colors
  ]
}

👀 Document List Preview

The plugin provides a component that you can use as a media preview of your icon within your document list.
You can pass a second argument (a true boolean value) to the function if you want to see always the original icon.

import {defineField, defineType} from 'sanity'
import {mediaPreview} from 'sanity-plugin-icon-manager'

const SampleDocument = defineType({
  type: 'document',
  name: 'sampleDocument',
  title: 'Sample Document',
  preview: {
    select: {
      // ...
      icon: 'icon'
    },
    prepare({icon, ...rest}) {
      return {
        // ...rest
        media: mediaPreview(icon)
      }
    }
  }
  fields: [
    // ...
    defineField({
      type: 'icon.manager',
      name: 'icon',
      title: 'Icon',
    }),
    // ...
  ],
})

export default SampleDocument

🧩 Add Icons to Portable Text

You can easily use the plugin inside your Portable Text, both for inline or block components. The preview will shows the rendered icon and its related name.

import {defineField, defineType} from 'sanity'

const SampleDocument = defineType({
  type: 'document',
  name: 'sampleDocument',
  title: 'Sample Document',
  fields: [
    // ...
    defineField({
      name: 'body',
      type: 'array',
      title: 'Body',
      of: [
        {
          type: 'block',
          of: [{type: 'icon.manager', title: 'Inline Icon'}],
        },
        {
          type: 'icon.manager',
          title: 'Block Icon',
        },
      ],
    }),
    // ...
  ],
})

export default SampleDocument

🎨 Custom Color Palette

You can pass a list of custom colors to fill your monochrome icons with your brand identity. You need to provide a list of valid hex colors (with an optional title).
As a result, you will have access to these colors within the color picker when customizing a monochrome icon.

import {defineConfig} from 'sanity'
import {IconManager} from 'sanity-plugin-icon-manager'

export default defineConfig({
  //...
  plugins: [
    IconManager({
      customPalette: [
        {
          hex: '#AB87FF',
          title: 'Tropical Indigo',
        },
        {
          hex: '#B4E1FF',
          title: 'Uranian Blue',
        },
        {
          hex: '#F49E4C',
          title: 'Sandy brown',
        },
        {
          hex: '#2D728F',
          title: 'Cerulean',
        },
        {
          hex: '#C14953',
          title: 'Bittersweet shimmer',
        },
        {
          hex: '#AEA4BF',
          title: 'Rose quartz',
        },
        {
          hex: '#02C39A',
          title: 'Mint',
        },
      ],
    }),
  ],
  // ...
})

🎭 Custom Diff View

The plugin includes a custom diff component that allows you to view differences in a more human-readable way. You can have three different custom diff views:

Icon Added

Icon Changed

Icon Removed

In any of the above cases you can always see the list of all the changes clicking on the Show details CTA.

🗂️ Collections Tab

Starting from v.1.2.0, you can browse icons through all available collections.
The search dialog now offers a 'Tabs view' where you can choose to search for your icons as before or via the new 'Collections' tab. Here, you can scroll through all the available collections, select one, and choose an icon from the available options within the selected collection.

🌎 Basic Hosting

The Iconify project allows you to host the API on your server. You can learn more about it in their official documentation.
This plugin offers a basic customization through the customEndpoint option. If you pass a valid URL, hosting a custom Iconify implementation, the plugin will use it as the base path for all the interactions (searching and rendering).

import {defineConfig} from 'sanity'
import {IconManager} from 'sanity-plugin-icon-manager'

export default defineConfig({
  //...
  plugins: [
    IconManager({
      customEndpoint: 'https://my.iconify.project.com',
    }),
  ],
  // ...
})

🗃️ Data model

  {
    _type: 'icon.manager',
    icon: string
    metadata: {
      iconName: string
      collectionId: string
      collectionName: string
      url: string
      downloadUrl: string
      inlineSvg: string
      hFlip: boolean
      vFlip: boolean
      flip: 'horizontal' | 'vertical' | 'horizontal,vertical'
      rotate: 0 | 1 | 2 | 3
      size: {
        width: number
        height: number
      }
      color: {
        hex: string
        rgba: {
          r: number
          g: number
          b: number
          a: number
        }
      }
      palette: boolean
      author: {
        name: string
        url: string
      },
      license: {
        name: string
        url: string
      }
    }
  }

🎬 How to render the icon on your website

Regardless of how you retrieve data from Sanity, you can render the icon in different ways.
You can use the inline option to render the SVG directly. Alternatively, Iconify provides various rendering possibilities:

Here an example with the React package:

// Let's assume that we have retrieved the following data from Sanity

{
  icon: 'bi:check2-circle',
  metadata: {
    flip: 'horizontal',
    size: {
      width: 20,
      height: 20,
    },
    rotate: 0,
    color: {
      hex: '#6aceeb'
    }
  }
}

------------------------------------------------------------------------------------

import {Icon} from '@iconify/react'

const MyComponent = (props) => {
  const {icon, metadata: {flip, rotate, size, color} } = props
  return (
    <Icon
      icon={icon}
      flip={flip}
      rotate={rotate}
      width={size.width}
      height={size.height}
      style={{color: color.hex}}
    />
  )
}

🛣️ Roadmap

~~Filter by Collection~~ (v1.1.0+)
~~Search within an entire collection~~ (v1.2.0+)
Analyze the possibility of adding custom icon sets via configuration
🤔

📝 License

🧪 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.

Release new version

Run "CI & Release" workflow. Make sure to select the main branch and check "Release new version".

Semantic release will only release on configured branches, so it is safe to run release on any branch.