# @snack-uikit/list

> `npm i @snack-uikit/list`

Latest version **1.0.1** (published 2026-09-21) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @snack-uikit/list
pnpm add @snack-uikit/list
yarn add @snack-uikit/list
bun add @snack-uikit/list
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2026-09-21 |
| First published | 2024-01-30 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 14 |
| Unpacked size | 493.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 23 |
| Author | Nikita Ershov |
| Maintainers | yetihead, agrigorii, cloud-ru-tech |

## Links

- npm: https://www.npmjs.com/package/@snack-uikit/list
- Repository: https://github.com/cloud-ru-tech/snack-uikit.git#master
- Homepage: https://cloud-ru-tech.github.io/snack-uikit/packages/list
- Issues: https://github.com/cloud-ru-tech/snack-uikit/issues
- npm.io page: https://npm.io/package/@snack-uikit/list

## Dependencies (14)

- [classnames](https://npm.io/package/classnames.md) ^2.5.1
- [merge-refs](https://npm.io/package/merge-refs.md) ^1.3.0
- [@snack-uikit/icons](https://npm.io/package/@snack-uikit/icons.md) ^1.0.1
- [@snack-uikit/utils](https://npm.io/package/@snack-uikit/utils.md) ^5.0.0
- [@snack-uikit/button](https://npm.io/package/@snack-uikit/button.md) ^1.0.1
- [@snack-uikit/scroll](https://npm.io/package/@snack-uikit/scroll.md) ^1.0.1
- [@snack-uikit/divider](https://npm.io/package/@snack-uikit/divider.md) ^4.0.0
- [@snack-uikit/loaders](https://npm.io/package/@snack-uikit/loaders.md) ^1.0.1
- [@snack-uikit/toggles](https://npm.io/package/@snack-uikit/toggles.md) ^1.0.1
- [@snack-uikit/dropdown](https://npm.io/package/@snack-uikit/dropdown.md) ^1.0.1
- [@snack-uikit/info-block](https://npm.io/package/@snack-uikit/info-block.md) ^1.0.1
- [@tanstack/react-virtual](https://npm.io/package/@tanstack/react-virtual.md) ^3.11.2
- [@snack-uikit/search-private](https://npm.io/package/@snack-uikit/search-private.md) ^1.0.1
- [@snack-uikit/truncate-string](https://npm.io/package/@snack-uikit/truncate-string.md) ^1.0.1

## Recent versions

- 1.0.1 (latest) — 2026-09-21
- 1.0.1-preview-acb79d0b.0 (preview) — 2026-09-21
- 1.0.1-preview-b2e4ed46.0 — 2026-09-21
- 1.0.1-preview-27969f64.0 — 2026-09-21
- 1.0.1-preview-fe85442f.0 — 2026-09-18
- 0.34.0 — 2026-09-15
- 0.33.5-preview-620fd545.0 — 2026-09-09
- 0.33.5-preview-fc6b5b87.0 — 2026-08-20
- 0.33.4 — 2026-08-07
- 0.33.4-preview-4e8bfebd.0 — 2026-08-07
- 0.33.4-preview-eff3bc02.0 — 2026-08-03
- 0.33.3 — 2026-07-03
- 0.33.3-preview-74429015.0 — 2026-07-03
- 0.33.3-preview-02d918ac.0 — 2026-07-03
- 0.33.3-preview-6a625dbd.0 — 2026-06-30
- … 354 more at https://npm.io/package/@snack-uikit/list/versions

## README

# List

## Installation

`npm i @snack-uikit/list`

[Changelog](./CHANGELOG.md)

## Description

- Пакет `@snack-uikit/list` предоставляет компоненты для отображения структурированных списков с поддержкой выбора элементов, поиска, группировки и вложенных структур.
- Компоненты поддерживают различные типы элементов: базовые элементы, группы, аккордеоны и вложенные списки, а также режимы выбора (одиночный, множественный, без выбора).
- Списки поддерживают закрепление элементов сверху и снизу, кастомный футер, поисковую строку, виртуализацию для больших объёмов данных и полноценную навигацию с клавиатуры.
- Компоненты работают в контролируемом и неконтролируемом режимах, поддерживают состояния загрузки и пустых данных, а также настраиваемые экраны для различных сценариев (нет данных, нет результатов поиска, ошибка).

## List

### Description

- `List` — компонент для отображения структурированного списка элементов, встраиваемого непосредственно в контент страницы.
- Поддерживает **режимы выбора** элементов: одиночный (`selection.mode="single"`), множественный (`selection.mode="multiple"`) и без выбора (`selection` не передан).
- Позволяет **закреплять элементы** сверху (`pinTop`) и снизу (`pinBottom`), которые остаются видимыми при прокрутке основного списка.
- Включает **поисковую строку** (`search`) для фильтрации элементов по содержимому.
- Поддерживает **различные типы элементов**: базовые элементы, группы с заголовками, аккордеоны с раскрывающимся контентом и вложенные списки (`next-list`).
- Может отображать **кастомный футер** (`footer`) с дополнительными элементами управления.
- Поддерживает **виртуализацию** (`virtualized`) для оптимизации рендеринга больших списков (от 1000 элементов).
- Обеспечивает **навигацию с клавиатуры** с поддержкой стрелок, Enter, Space и других клавиш для перемещения и выбора элементов.
- Позволяет настраивать **состояния пустых данных** (`noDataState`, `noResultsState`, `errorDataState`) для различных сценариев.
- Figma: [`List`](https://www.figma.com/file/jtGxAPvFJOMir7V0eQFukN/Snack-UI-Kit-1.0.0?node-id=41%3A7631&mode=design).

### Example

```tsx
import { List } from '@snack-uikit/list';

function Example() {
  const [selected, setSelected] = useState<string | undefined>();

  return (
    <List
      items={[
        {
          id: '1',
          content: { option: 'Первый элемент', description: 'Описание первого элемента' },
        },
        {
          id: '2',
          content: { option: 'Второй элемент', description: 'Описание второго элемента' },
        },
      ]}
      selection={{
        mode: 'single',
        value: selected,
        onChange: setSelected,
      }}
      search={{
        value: '',
        onChange: (value) => console.log('Search:', value),
        placeholder: 'Поиск...',
      }}
      pinTop={[
        {
          id: 'pinned-top',
          content: { option: 'Закреплённый элемент сверху' },
        },
      ]}
      footer={<button>Дополнительное действие</button>}
    />
  );
}
```

## Droplist

### Description

- `Droplist` — компонент выпадающего списка, который отображается в поповере при взаимодействии с триггером (кнопкой, ссылкой или другим элементом).
- Объединяет функциональность `List` с возможностями выпадающего меню: появляется по клику, ховеру, фокусу или другим триггерам и автоматически позиционируется относительно элемента-триггера.
- Поддерживает **различные триггеры открытия** (`trigger`): `click`, `hover`, `focus`, `focusVisible` и их комбинации.
- Позволяет настраивать **позиционирование** (`placement`) относительно триггера: сверху, снизу, слева, справа и их вариации.
- Может **автоматически закрываться** после выбора элемента (`closeDroplistOnItemClick`) в режимах без выбора или одиночного выбора.
- Поддерживает **управление шириной** поповера (`widthStrategy`): автоматическая, равная триггеру или больше триггера.
- Включает все возможности `List`: выбор элементов, поиск, группировка, закрепление элементов, виртуализация и навигация с клавиатуры.
- Триггер может быть передан как React-элемент или функция-рендер, которая получает обработчик `onKeyDown` для поддержки навигации с клавиатуры.
- Figma: [`Droplist`](https://www.figma.com/file/jtGxAPvFJOMir7V0eQFukN/Snack-UI-Kit-1.0.0?node-id=41%3A7631&mode=design).

### Example

```tsx
import { Droplist } from '@snack-uikit/list';
import { ButtonFilled } from '@snack-uikit/button';

function Example() {
  const [selected, setSelected] = useState<string | undefined>();

  return (
    <Droplist
      items={[
        {
          id: '1',
          content: { option: 'Первый элемент', description: 'Описание первого элемента' },
        },
        {
          id: '2',
          content: { option: 'Второй элемент', description: 'Описание второго элемента' },
        },
      ]}
      selection={{
        mode: 'single',
        value: selected,
        onChange: setSelected,
      }}
      trigger="click"
      placement="bottom-start"
      closeDroplistOnItemClick
    >
      <ButtonFilled label="Выбрать элемент" />
    </Droplist>
  );
}
```

[//]: DOCUMENTATION_SECTION_START
[//]: THIS_SECTION_IS_AUTOGENERATED_PLEASE_DONT_EDIT_IT
## kindFlattenItems
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
| items* | `Item[]` | - |  |
| prefix | `ItemId` | - |  |
| parentId | `ItemId` | - |  |
## isAccordionItem
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
## isBaseItem
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
## isGroupItem
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
## isNextListItem
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
## isGroupSelectItem
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
## useGroupItemSelection
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
| id* | `ItemId` | - |  |
| items* | `ItemId[]` | - |  |
| allChildIds* | `ItemId[]` | - |  |
| disabled | `boolean` | - |  |
## isSelectionSingleProps
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
## isSelectionMultipleProps
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
## Droplist
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
| items* | `Item[]` | - | Основные элементы списка |
| children* | `ReactNode \| ({onKeyDown}) => ReactNode * Рендер функция принимает аргументы `onKeyDown` - хендлер ввода, для поддержки управления с клавиатуры` | - | Триггер для дроплиста |
| triggerElemRef | `RefObject<HTMLElement>` | - | Ссылка на элемент-триггер для дроплиста |
| listRef | `RefObject<HTMLElement>` | - | Ссылка на элемент выпадающего списка |
| closeDroplistOnItemClick | `boolean` | - | Закрывать выпадающий список после клика на базовый айтем.  Работает в режимах selection: 'none' \| 'single' |
| virtualized | `boolean` | - | Включить виртуализацию на компоненты списка. Рекомендуется если у вас от 1к элементов списка |
| triggerClassName | `string` | - | CSS-класс триггера |
| open | `boolean` | - | Управляет состоянием показан/не показан. |
| onOpenChange | `(isOpen: boolean) => void` | - | Колбек отображения компонента. Срабатывает при изменении состояния open. |
| widthStrategy | enum PopoverWidthStrategy: `"auto"`, `"gte"`, `"eq"` | auto | Стратегия управления шириной контейнера поповера <br> - `auto` - соответствует ширине контента, <br> - `gte` - Great Than or Equal, равен ширине таргета или больше ее, если контент в поповере шире, <br> - `eq` - Equal, строго равен ширине таргета. |
| closeOnPopstate | `boolean` | - | Закрывать ли поповер при пекреходе по истории браузера |
| trigger | enum Trigger: `"click"`, `"hover"`, `"focusVisible"`, `"focus"`, `"hoverAndFocusVisible"`, `"hoverAndFocus"`, `"clickAndFocusVisible"` | - | Условие отображения поповера: <br> - `click` - открывать по клику <br> - `hover` - открывать по ховеру <br> - `focusVisible` - открывать по focus-visible <br> - `focus` - открывать по фокусу <br> - `hoverAndFocusVisible` - открывать по ховеру и focus-visible <br> - `hoverAndFocus` - открывать по ховеру и фокусу <br> - `clickAndFocusVisible` - открывать по клику и focus-visible |
| placement | enum Placement: `"left"`, `"left-start"`, `"left-end"`, `"right"`, `"right-start"`, `"right-end"`, `"top"`, `"top-start"`, `"top-end"`, `"bottom"`, `"bottom-start"`, `"bottom-end"` | top | Положение поповера относительно своего триггера (children). |
| className | `string` | - | CSS-класс |
| pinTop | `Item[]` | - | Элементы списка, закрепленные сверху |
| pinBottom | `Item[]` | - | Элементы списка, закрепленные снизу |
| footer | `ReactNode ;` | - | Кастомизируемый элемент в конце списка |
| footerActiveElementsRefs | `RefObject<HTMLElement>[]` | - | Список ссылок на кастомные элементы, помещенные в специальную секцию внизу списка |
| search | `SearchState` | - | Настройки поисковой строки |
| collapse | `CollapseState` | {} | Настройки раскрытия элементов |
| loading | `boolean` | - | Флаг, отвещающий за состояние загрузки списка |
| scrollToSelectedItem | `boolean` | - | Флаг, отвещающий за прокручивание до выбранного элемента |
| scrollContainerClassName | `string` | - | CSS-класс для scroll обертки основного списка айтемов |
| selection | `SelectionSingleState \| SelectionMultipleState` | - |  |
| size | "s" \| "m" \| "l" | s | Размер списка |
| marker | `boolean` | true | Отображать ли маркер у выбранного жлемента списка |
| contentRender | `(props: ContentRenderProps) => ReactNode` | - | Рендер функция основного контента айтема |
| scroll | `boolean` | - | Включить ли скролл для основной части списка |
| scrollRef | `Ref<HTMLElement>` | - | Ссылка на элемент, обозначающий самый конец прокручиваемого списка |
| scrollContainerRef | `Ref<HTMLElement>` | - | Ссылка на контейнер, который скроллится |
| untouchableScrollbars | `boolean` | - | Отключает возможность взаимодействовать со скролбарами мышью. |
| barHideStrategy | enum BarHideStrategy: `"scroll"`, `"move"`, `"never"`, `"leave"` | - | Управление скрытием скролл баров: <br> - `Never` - показывать всегда <br> - `Leave` - скрывать когда курсор покидает компонент <br> - `Scroll` - показывать только когда происходит скроллинг <br> - `Move` - показывать при движении курсора над компонентом |
| onScroll | `(event?: Event) => void` | - | Колбек на скролл прокручиваемого списка |
| dataFiltered | `boolean` | - |  |
| dataError | `boolean` | - |  |
| noDataState | `EmptyStateProps` | - | Экран при отстутствии данных |
| noResultsState | `EmptyStateProps` | - | Экран при отстутствии результатов поиска или фильтров |
| errorDataState | `EmptyStateProps` | - | Экран при ошибке запроса |
## List
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
| items* | `Item[]` | - | Основные элементы списка |
| pinTop | `Item[]` | - | Элементы списка, закрепленные сверху |
| pinBottom | `Item[]` | - | Элементы списка, закрепленные снизу |
| footer | `ReactNode ;` | - | Кастомизируемый элемент в конце списка |
| footerActiveElementsRefs | `RefObject<HTMLElement>[]` | - | Список ссылок на кастомные элементы, помещенные в специальную секцию внизу списка |
| keyboardNavigationRef | `RefObject<{ focusItem(id: ItemId): void; }>` | - | Ссылка на управление навигацией листа с клавиатуры |
| search | `SearchState` | - | Настройки поисковой строки |
| tabIndex | `number` | - | Tab Index |
| collapse | `CollapseState` | {} | Настройки раскрытия элементов |
| className | `string` | - | CSS-класс |
| loading | `boolean` | - | Флаг, отвещающий за состояние загрузки списка |
| onKeyDown | `(e: KeyboardEvent<HTMLElement>) => void` | - | Обработчик события по нажатию клавиш |
| hasListInFocusChain | `boolean` | true | Флаг, отвещающий за включение самого родительского контейнера листа в цепочку фокусирующихся элементов |
| scrollToSelectedItem | `boolean` | - | Флаг, отвещающий за прокручивание до выбранного элемента |
| scrollContainerClassName | `string` | - | CSS-класс для scroll обертки основного списка айтемов |
| virtualized | `boolean` | - | Включить виртуализацию на компоненты списка. Рекомендуется если у вас от 1к элементов списка |
| selection | `SelectionSingleState \| SelectionMultipleState` | - |  |
| size | "s" \| "m" \| "l" | s | Размер списка |
| marker | `boolean` | true | Отображать ли маркер у выбранного жлемента списка |
| contentRender | `(props: ContentRenderProps) => ReactNode` | - | Рендер функция основного контента айтема |
| scroll | `boolean` | - | Включить ли скролл для основной части списка |
| scrollRef | `Ref<HTMLElement>` | - | Ссылка на элемент, обозначающий самый конец прокручиваемого списка |
| scrollContainerRef | `Ref<HTMLElement>` | - | Ссылка на контейнер, который скроллится |
| untouchableScrollbars | `boolean` | - | Отключает возможность взаимодействовать со скролбарами мышью. |
| barHideStrategy | enum BarHideStrategy: `"scroll"`, `"move"`, `"never"`, `"leave"` | - | Управление скрытием скролл баров: <br> - `Never` - показывать всегда <br> - `Leave` - скрывать когда курсор покидает компонент <br> - `Scroll` - показывать только когда происходит скроллинг <br> - `Move` - показывать при движении курсора над компонентом |
| onScroll | `(event?: Event) => void` | - | Колбек на скролл прокручиваемого списка |
| dataFiltered | `boolean` | - |  |
| dataError | `boolean` | - |  |
| noDataState | `EmptyStateProps` | - | Экран при отстутствии данных |
| noResultsState | `EmptyStateProps` | - | Экран при отстутствии результатов поиска или фильтров |
| errorDataState | `EmptyStateProps` | - | Экран при ошибке запроса |
| ref | `LegacyRef<HTMLElement>` | - | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). @see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs} |
| key | `Key` | - |  |
## ItemContent
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
| option* | `string \| number` | - |  |
| caption | `string` | - |  |
| description | `string` | - |  |
| truncate | `TruncateProps` | - |  |
| disabled | `boolean` | - |  |
| className | `string` | - | CSS-класс |
## getFooterItemId
`helper` 

Возвращает id для элемента футера
## getItemAutoId
`helper` 

Возвращает id для элемента, подставляя перфикс
## getDefaultItemId
`helper` 

Возвращает id для дефолтного элемента


[//]: DOCUMENTATION_SECTION_END

---
_Source: https://npm.io/package/@snack-uikit/list · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._