ui/docs/content/1.getting-started/4.icons.md

description

description

You can use any icon (100,000+) from Iconify.

Some components have an icon prop that allows you to add an icon to the component.

<template>
  <UButton icon="i-heroicons-magnifying-glass" />
</template>

You can also use the Icon component to add an icon anywhere in your app by following this pattern: i-{collection_name}-{icon_name}.

<template>
  <UIcon name="i-heroicons-moon" />
</template>

Collections

By default, the module uses Heroicons but you can change it from the module options in your nuxt.config.ts.

export default defineNuxtConfig({
  ui: {
    icons: ['mdi', 'simple-icons']
  }
})

::callout{icon="i-heroicons-light-bulb"} Search the icon you want to use on https://icones.js.org built by @antfu. ::

Thanks to @egoist/tailwindcss-icons plugin, only the icons you use in your app will be bundled in your CSS. However, you need to install the icon collections you specified in the ui.icons key:

::code-group

pnpm i @iconify-json/{collection_name}

yarn add @iconify-json/{collection_name}

npm install @iconify-json/{collection_name}

::

If you choose to use the full @iconify/json icon collection (50MB), you can specifiy icons: 'all' or icons: {} in your nuxt.config.ts to use any icon in your app.

export default defineNuxtConfig({
  ui: {
    icons: {}
  }
})

Custom config

If you have specific needs, like using a custom icon collection, you can use the icons option in your nuxt.config.ts as an object to override the config of the @egoist/tailwindcss-icons plugin.

import { getIconCollections } from '@egoist/tailwindcss-icons'

export default defineNuxtConfig({
  ui: {
    icons: {
      // might solve stretch bug on generate, see https://github.com/egoist/tailwindcss-icons/issues/23
      extraProperties: {
        'mask-size': 'contain',
        'mask-position': 'center'
      },
      collections: {
        foo: {
          icons: {
            'arrow-left': {
              // svg body
              body: '<path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M10.5 19.5L3 12m0 0l7.5-7.5M3 12h18" />',
              // svg width and height, optional
              width: 24,
              height: 24
            }
          }
        },
        ...getIconCollections(['heroicons', 'simple-icons'])
      }
    }
  }
})

Dynamic icons

The Icon component also has a dynamic prop to use the nuxt-icon module instead of the @egoist/tailwindcss-icons plugin.

Read more about this in the Icon component page.

Defaults

You can easily replace all the default icons of the components in your app.config.ts.

export default defineAppConfig({
  ui: {
    button: {
      default: {
        loadingIcon: 'i-octicon-sync-24'
      }
    },
    input: {
      default: {
        loadingIcon: 'i-octicon-sync-24'
      }
    },
    select: {
      default: {
        loadingIcon: 'i-octicon-sync-24',
        trailingIcon: 'i-octicon-chevron-down-24'
      }
    },
    selectMenu: {
      default: {
        selectedIcon: 'i-octicon-check-24'
      }
    },
    notification: {
      default: {
        closeButton: {
          icon: 'i-octicon-x-24'
        }
      }
    },
    commandPalette: {
      default: {
        icon: 'i-octicon-search-24',
        loadingIcon: 'i-octicon-sync-24',
        selectedIcon: 'i-octicon-check-24',
        emptyState: {
          icon: 'i-octicon-search-24'
        }
      }
    },
    table: {
      default: {
        sortAscIcon: 'i-octicon-sort-asc-24',
        sortDescIcon: 'i-octicon-sort-desc-24',
        sortButton: {
          icon: 'i-octicon-arrow-switch-24'
        },
        loadingState: {
          icon: 'i-octicon-sync-24'
        },
        emptyState: {
          icon: 'i-octicon-database-24'
        }
      }
    },
    pagination: {
      default: {
        firstButton: {
          icon: 'i-octicon-chevron-left-24'
        },
        prevButton: {
          icon: 'i-octicon-arrow-left-24'
        },
        nextButton: {
          icon: 'i-octicon-arrow-right-24'
        },
        lastButton: {
          icon: 'i-octicon-chevron-right-24'
        }
      }
    },
    accordion: {
      default: {
        openIcon: 'i-octicon-chevron-down-24'
      }
    },
    breadcrumb: {
      default: {
        divider: 'i-octicon-chevron-right-24'
      }
    }
  }
})