Skip to content
ReferenceVersion 6.0.2

SVG Icons ​

tsx
import type { IconName } from '@ray-template/icons'
import { RIcon } from '@ray-template/ui/icon'

const name: IconName = 'directional/resize_h'

const renderIcon = () => <RIcon name={name} />

RIcon.name and route meta.icon use the same group-qualified names. For example, packages/icons/src/business/orders/approved.svg becomes business/orders/approved. Search and copy usage from the SVG Icons demo.

Interactive example ​

The icon library copies TSX by default, such as <RIcon name="action/search" />. Select Vue template and click an icon to copy <r-icon name="action/search" /> for a Vue template that imports RIcon.

View example source
tsx
import './index.scss'
import { useI18n } from '@/hooks'
import { iconNames, iconPackages } from '@/icons'
import { RIcon } from '@ray-template/ui/icon'
import {
  NCard,
  NEmpty,
  NInput,
  NRadioButton,
  NRadioGroup,
  NSelect,
} from 'naive-ui'
import DemoPage from '../components/DemoPage'

export default defineComponent({
  name: 'PreviewSVGIcons',
  setup() {
    const { t } = useI18n('icons')
    const { t: showcaseT } = useI18n('showcase')
    const query = ref('')
    const selectedPackage = ref<string | null>(null)
    const copyFormat = ref<'tsx' | 'vue'>('tsx')
    const copyTag = computed(() =>
      copyFormat.value === 'tsx' ? 'RIcon' : 'r-icon',
    )
    const filtered = computed(() =>
      iconNames.filter(
        (name) =>
          (!selectedPackage.value ||
            name.startsWith(`${selectedPackage.value}/`)) &&
          name.includes(query.value.trim().toLowerCase()),
      ),
    )
    const groups = computed(() =>
      iconPackages
        .map((name) => ({
          name,
          icons: filtered.value.filter((icon) => icon.startsWith(`${name}/`)),
        }))
        .filter((group) => group.icons.length),
    )

    return () => (
      <DemoPage
        title={t<string>('title')}
        description={t<string>('description')}
        eyebrow={showcaseT<string>('iconsEyebrow')}
        meta={`${iconNames.length} SVG / ${iconPackages.length} ${t<string>('packagesLabel')}`}
      >
        <NCard class="r-icon-library">
          <div class="r-icon-library__toolbar">
            <NInput
              class="r-icon-library__search"
              value={query.value}
              onUpdateValue={(value) => {
                query.value = value
              }}
              placeholder={t<string>('search')}
              inputProps={{ 'aria-label': t<string>('search') }}
              clearable
            >
              {{ prefix: () => <RIcon name="action/search" size={16} /> }}
            </NInput>
            <NSelect
              class="r-icon-library__filter"
              value={selectedPackage.value}
              onUpdateValue={(value: string | null) => {
                selectedPackage.value = value
              }}
              options={iconPackages.map((value) => ({ label: value, value }))}
              clearable
              placeholder={t<string>('allPackages')}
            />
            <NRadioGroup
              v-model:value={copyFormat.value}
              aria-label={t<string>('copyFormat')}
            >
              <NRadioButton value="tsx">TSX</NRadioButton>
              <NRadioButton value="vue">{t('vueTemplate')}</NRadioButton>
            </NRadioGroup>
          </div>
          <div class="r-icon-library__hint">
            <span>
              {t('copy', {
                format: copyFormat.value === 'tsx' ? 'TSX' : t('vueTemplate'),
              })}
            </span>
            <span>
              {filtered.value.length} / {iconNames.length}
            </span>
          </div>
          {groups.value.map((group) => (
            <section class="r-icon-library__group" key={group.name}>
              <header>
                <h2>{group.name}</h2>
                <span>{group.icons.length}</span>
              </header>
              <div class="pre-view-icons__grid">
                {group.icons.map((name) => (
                  <button
                    type="button"
                    class="pre-view-icons__card"
                    key={name}
                    title={name}
                    aria-label={name}
                    v-copy={`<${copyTag.value} name="${name}" />`}
                  >
                    <RIcon name={name} size={28} cursor="pointer" />
                    <span>{name.split('/').slice(1).join('/')}</span>
                  </button>
                ))}
              </div>
            </section>
          ))}
          {!filtered.value.length ? (
            <NEmpty description={t<string>('empty')} />
          ) : null}
        </NCard>
      </DemoPage>
    )
  },
})

Add and generate icons ​

  1. Choose an existing group such as action, navigation, or system, or create a business group. Start path segments with a letter and use lowercase letters, digits, underscores, or hyphens.
  2. Use currentColor for monochrome icons and none for empty areas. Keep brand colors.
  3. The dev server or pnpm icons:generate updates packages/icons/src/manifest.ts. Verify with pnpm icons:check and commit the manifest with the SVGs. Generate the union type from the files.

Production builds generate a separate hashed sprite per top-level group, loaded under the deployment base. Replace bare names in old source. Cached bare names are migrated only if the filename is unique.

Icon workflow and group map

RIcon API ​

@/components exports RIcon, IconProps, iconProps, IconName, and IconPackage. @/icons also exports the icon types.

PropDefaultDescription
nameRequiredFull group-qualified path. The first segment selects the sprite.
size20Base width and height. Numbers are pixels, and CSS sizes are supported.
width / height0 / 0Override the base dimensions individually. 0 uses size.
color'currentColor'SVG fill. Brand icons with their own colors may retain them.
prefix'icon'Symbol prefix, which must match generation.
customClassNameNoneExtra class for the root.
depth1Icon opacity level.
cursor'inherit'Inherits the parent control's cursor.
onClick(event)NoneAccepts a callback or array.

The inner SVG is hidden from screen readers. For an action, wrap it in a button with an accessible name and preserve keyboard operation and focus.

RIcon props · Sprite reference implementation

Icon sources ​

Shared icons come from the IconPark outline collection on Iconfont. The source inventory lists names and Iconfont IDs by use. Monochrome icons follow text color. Ray and other brand marks retain their original colors.

Prefer existing icon names. Three retired assets migrate when loading old route configurations.

  • action/export_excel becomes action/download.
  • logo/office becomes navigation/table.
  • illustration/login_bg becomes navigation/other.

Use the new full names in new code.