Как работать с иконками

React-иконки поставляются в пакете @salutejs/sdds-icons с поддержкой tree-shaking. Иконки доступны в размерах 16, 24 и 36.

Установка​

npm install @salutejs/sdds-icons

Совместимость​

Пакет поставляется только в формате ES Modules. Для его использования необходимы:

  • синтаксис import;
  • сборщик с поддержкой поля exports в package.json;
  • TypeScript с moduleResolution, равным bundler, node16 или nodenext.

CommonJS и require() не поддерживаются:

// Не поддерживается
const icons = require('@salutejs/sdds-icons/24');

Использование​

Выберите размер иконки в пути импорта. Пакет поддерживает именованный импорт из общего файла размера:

import { AddFill } from '@salutejs/sdds-icons/24';

export const AddButton = () => <AddFill />;

Также доступен прямой импорт конкретной иконки. Он позволяет сборщику не обрабатывать общий файл со всеми иконками выбранного размера:

import AddFill from '@salutejs/sdds-icons/24/AddFill';

export const AddButton = () => <AddFill />;

У пакета нет экспорта из корня, поэтому размер необходимо указывать всегда. Доступны размеры 16, 24 и 36:

import { AddFill as AddFill16 } from '@salutejs/sdds-icons/16';
import { AddFill as AddFill24 } from '@salutejs/sdds-icons/24';
import { AddFill as AddFill36 } from '@salutejs/sdds-icons/36';

Каждая точка входа содержит только SVG-иконки соответствующего размера. Компоненты создают один элемент svg, наследуют цвет через currentColor, поддерживают ref и принимают стандартные свойства SVG.

Размер по умолчанию соответствует выбранному варианту. Отображаемые ширину и высоту можно переопределить стандартными SVG-свойствами:

<AddFill width={32} height={32} color="tomato" />

Через свойство gradient можно передать CSS-градиент. В этом случае оптимизированный SVG используется как CSS-маска, а градиент заполняет всю область иконки:

<AddFill gradient="linear-gradient(135deg, #00d6ff 0%, #9b51e0 100%)" />

Для отображения градиентов Content Security Policy приложения должна разрешать data: в директиве img-src.

Динамические иконки​

Если имя иконки приходит во время выполнения, например из CMS или с сервера, используйте отдельную динамическую точку входа нужного размера:

import { DynamicIcon } from '@salutejs/sdds-icons/24/dynamic';

export const ServerIcon = () => <DynamicIcon name="AddFill" />;

Иконка загружается отдельным модулем только после появления компонента в браузере. Пока модуль загружается, можно показать fallback-компонент:

import { DynamicIcon } from '@salutejs/sdds-icons/24/dynamic';

export const ServerIcon = () => <DynamicIcon name="AddFill" fallback={<span>Загрузка…</span>} />;

Для произвольной строки доступна проверка, которая одновременно сужает TypeScript-тип:

import { DynamicIcon, isIconName } from '@salutejs/sdds-icons/24/dynamic';

export const ServerIcon = ({ iconName }: { iconName: string }) =>
    isIconName(iconName) ? <DynamicIcon name={iconName} /> : null;

Также динамическая точка входа экспортирует IconName, iconNames и isIconName. Реестр загрузчиков остается внутренней деталью реализации DynamicIcon.

Динамический API предназначен только для случаев, когда имя заранее неизвестно. Он заставляет сборщик обработать весь реестр и создать отдельный модуль для каждой иконки на каждый размер. Для обычного интерфейса статические импорты быстрее при сборке и не требуют дополнительного запроса в браузере.

danger

Старый пакет @salutejs/plasma-icons будет поддерживаться до 31 декабря 2026.