Payload Info Tooltip: компактные подсказки для полей в админке Payload CMS

Чем сложнее проект на Payload CMS, тем больше пояснений приходится оставлять редакторам. У полей появляются admin.description, формы растягиваются, а действительно важные настройки теряются среди текста.

Для решения этой небольшой, но знакомой многим проблемы появился плагин @alphanull/payload-plugin-info-tooltip. Первая версия опубликована 17 октября 2026 года, код открыт под лицензией MIT.

Репозиторий проекта:

https://github.com/alphanull/payload-plugin-info-tooltip

Идея простая: вместо длинного текста под полем — маленькая иконка с информацией рядом с названием поля. Редактор видит компактную форму, а пояснение открывает только тогда, когда оно действительно понадобилось.

Отдельная подсказка для поля

Основной механизм плагина — значение admin.custom.infoTooltip. Его можно задать любому полю:

import type { CollectionConfig } from 'payload'

export const Pages: CollectionConfig = {
  slug: 'pages',
  fields: [
    {
      name: 'slug',
      type: 'text',
      admin: {
        custom: {
          infoTooltip: 'Используется для формирования адреса страницы',
        },
      },
    },
  ],
}

Подсказка необязательно должна заменять описание полностью. Можно оставить краткий текст под полем, а дополнительную информацию вынести в иконку — оба варианта работают одновременно.

Также плагин умеет показывать иконки в заголовках колонок списка документов — за это отвечает опция showInListView.

Автоматическое преобразование существующих описаний

Переписывать конфигурацию проекта специально ради плагина не обязательно. Режим useDescriptions: true превращает существующие admin.description в подсказки автоматически — подходят строки, объекты локалей и функции.

Устанавливается плагин обычным способом:

pnpm add @alphanull/payload-plugin-info-tooltip

Подключается как обычный плагин Payload:

import { buildConfig } from 'payload'
import { infoTooltipPlugin } from '@alphanull/payload-plugin-info-tooltip'

export default buildConfig({
  plugins: [
    infoTooltipPlugin({
      useDescriptions: true,
    }),
  ],
})

Это самая интересная часть для давно работающих проектов: плагин можно попробовать, не перерабатывая десятки конфигураций полей.

Полностью убирать обычные описания тоже не требуется. Отдельному полю можно вернуть видимый текст через infoTooltip: false — это явный отказ от преобразования:

{
  name: 'notes',
  type: 'textarea',
  admin: {
    description: 'Длинный поясняющий текст…',
    custom: {
      infoTooltip: false,
    },
  },
}

После изменения конфигурации нужно перегенерировать import map админки (pnpm payload generate:importmap); dev-сервер делает это сам. Важно закоммитить обновлённый файл: при next build он не генерируется.

Как устроен текст подсказки

infoTooltip принимает те же формы, что и admin.description: строку, объект локалей или функцию:

// Строка
infoTooltip: 'Используется в адресе страницы'

// Объект локалей
infoTooltip: {
  en: 'Used in the page URL',
  ru: 'Используется в адресе страницы',
}

// Функция
infoTooltip: ({ t }) => t('custom:slugInfo'),

Текст разрешается на сервере, для каждого запроса, на языке интерфейса админки: сначала активный язык, затем запасной, затем первый ключ. Функции в браузер не попадают — наружу уходит уже готовый текст. Это язык интерфейса, а не контентная локаль из переключателя языков.

Lexical, клавиатура и экранные дикторы

Плагин обрабатывает не только простые поля, но и вложенные структуры: табы, группы, массивы, блоки, а также поля внутри Lexical — поля ссылок, блоки и вложенные редакторы. Вызовы lexicalEditor менять не нужно: плагин обёртывает редактор и проходит по его фичам при каждой сборке конфигурации.

Подсказка реализована как полноценный элемент интерфейса, а не значок с HTML-атрибутом title. Она открывается наведением мыши, а тапом, Enter или Space переключается; закрытие — по Escape, клику вне подсказки или уходу фокуса. На текст в открытом окне можно навести указатель и выделить его. Для экранных дикторов текст читается как описание иконки, а лишнюю позицию в tab-порядке можно отключить опцией focusable: false.

Внешний вид настраивается через CSS-переменные; используются токены Payload 4 с откатом на Payload 3. Для собственных нестандартных меток предусмотрены компоненты LabelWithInfo и InfoTooltip и опция labelComponent, которая подменяет метки по правилу — например, для всех richText-полей сразу.

Совместимость и ограничения

В peerDependencies заявлены Payload ^3.90.2 || ^4.0.0-0. Автор протестировал плагин на Payload 3.90.2, 3.91.0 и бета-версиях 4.0.0-beta.0 и beta.2 — то есть и на актуальной ветке Payload 3, и на Payload 4 beta.

Ограничения стоит знать заранее:

• Плагин запускается последним через механизм order, который сам Payload помечает как экспериментальный.
• Поля с собственными компонентами admin.components.Description не преобразуются; описания табов тоже — Payload рендерит их заголовок простым текстом, без слота под иконку.
• В Payload 4 экспериментальное поле slug рисует метку и описание само, поэтому иконки там не будет.
• Проход по полям внутри Lexical использует внутренние механизмы Lexical, то есть самая хрупкая часть плагина именно там.

Насколько доверять

Проекту меньше недели: версия 1.0.1 вышла в тот же день, что и 1.0.0, звёзд на GitHub пока единицы. Поэтому мы бы рекомендовали воспринимать его как удобную утилиту, которую легко проверить, а не как проверенную временем зависимость.

С другой стороны, риск пробы минимальный. Плагин не меняет данные и схему, а режим useDescriptions не удаляет описания из конфигурации — они остаются на месте и по-прежнему попадают в JSDoc при generate:types. Если результат не понравится, подключение плагина просто откатывается.

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

Источники

https://github.com/alphanull/payload-plugin-info-tooltip