# Table

Таблиця зі сортуванням, станами завантаження і мобільними картками з тих самих слотів.


## Приклад


Example (app/demos/table/TableBasic.vue):

```vue
<script setup lang="ts">
import { ref } from 'vue'
import UiChip from '~/components/ui/UiChip.vue'
import UiTable, { type TableHeader, type TableSort } from '~/components/ui/UiTable.vue'

// Звичайний interface — таблиця приймає його без `extends Record<…>`.
interface Page {
  id: number
  title: string
  views: number
  status: 'published' | 'draft'
}

const headers: TableHeader[] = [
  { value: 'title', text: 'Сторінка', sortable: true, width: 200, flex: true },
  { value: 'views', text: 'Перегляди', sortable: true, align: 'right', width: 130, defaultSortDir: 'desc' },
  { value: 'status', text: 'Статус', width: 140 },
]

// «Файл 10» проти «Файл 9» — саме те, на чому наївне сортування помиляється.
const items = ref<Page[]>([
  { id: 1, title: 'Розділ 2', views: 1284, status: 'published' },
  { id: 2, title: 'Розділ 10', views: 87, status: 'draft' },
  { id: 3, title: 'Розділ 9', views: 22910, status: 'published' },
  { id: 4, title: 'Вступ', views: 431, status: 'draft' },
])

const sort = ref<TableSort | null>({ by: 'views', dir: 'desc' })
</script>

<template>
  <div class="w-full">
    <UiTable v-model:sort="sort" :headers="headers" :items="items" mobile-cards row-clickable>
      <template #cell-views="{ item }">
        {{ (item.views as number).toLocaleString('uk') }}
      </template>
      <!-- Без label: видимий текст уже і є назвою. label замінив би його для
           скрінрідера — і той почув би сирий код «published». -->
      <template #cell-status="{ item }">
        <UiChip :tone="item.status === 'published' ? 'success' : 'neutral'" dot>
          {{ item.status === 'published' ? 'опубліковано' : 'чернетка' }}
        </UiChip>
      </template>
    </UiTable>
    <p class="mt-2 text-xs text-muted">
      Сортування: {{ sort ? `${sort.by} / ${sort.dir}` : 'скинуто' }} — третій клік по заголовку скидає.
    </p>
  </div>
</template>

```


## Налаштування колонок

Задайте `tableId` — і вмикається все одразу: ресайз межею заголовка, меню
видимості й порядку, перемикач щільності та збереження в `localStorage`.


Example (app/demos/table/TableSettings.vue):

```vue
<script setup lang="ts">
import { ref } from 'vue'
import UiTable, { type TableHeader } from '~/components/ui/UiTable.vue'

interface Row extends Record<string, unknown> {
  id: number
  sku: string
  name: string
  vendor: string
  price: number
  stock: number
  note: string
}

/**
 * `flex: true` рівно на одній колонці — вона забирає залишок ширини.
 * Сума фіксованих має вміщатись у контейнер.
 */
const headers: TableHeader[] = [
  { value: 'sku', text: 'SKU', width: 80, sortable: true, required: true },
  { value: 'name', text: 'Назва', width: 170, sortable: true, flex: true },
  { value: 'vendor', text: 'Постачальник', width: 120, sortable: true },
  { value: 'price', text: 'Ціна', width: 90, sortable: true, align: 'right' },
  { value: 'stock', text: 'Залишок', width: 80, sortable: true, align: 'right' },
  { value: 'note', text: 'Примітка', width: 150, clamp: 2 },
]

const items = ref<Row[]>([
  { id: 1, sku: 'AB-1', name: 'Кабель USB-C 2 м', vendor: 'Мережа Плюс', price: 249, stock: 12, note: 'Доставка з Києва протягом доби. Залишок оновлюється щогодини.' },
  { id: 2, sku: 'AB-10', name: 'Кабель USB-C 0.5 м', vendor: 'Мережа Плюс', price: 149, stock: 3, note: 'Мала партія.' },
  { id: 3, sku: 'AB-9', name: 'Перехідник HDMI', vendor: 'Технохаб', price: 599, stock: 0, note: 'Немає в наявності, очікується поповнення наступного тижня.' },
  { id: 4, sku: 'CD-2', name: 'Док-станція 7-в-1', vendor: 'Технохаб', price: 2490, stock: 5, note: '' },
  { id: 5, sku: 'CD-7', name: 'Хаб USB-C 4 порти', vendor: 'Мережа Плюс', price: 890, stock: 27, note: 'Хіт продажів сезону.' },
  { id: 6, sku: 'EF-3', name: 'Зарядний пристрій 65 Вт GaN', vendor: 'Технохаб', price: 1290, stock: 8, note: 'Компактний блок із двома USB-C.' },
])
</script>

<template>
  <div class="w-full space-y-2">
    <UiTable
      :headers="headers"
      :items="items"
      table-id="demo-catalog"
      :settings-version="2"
      max-height="18rem"
      sticky-header
      sticky-column
      mobile-cards
    >
      <template #cell-price="{ item }">{{ (item.price as number).toLocaleString('uk') }} ₴</template>
    </UiTable>

    <p class="text-xs text-muted">
      Потягніть межу заголовка, щоб змінити ширину; подвійний клік скидає.
      Наведіть на таблицю — у правому куті шапки з'явиться кнопка
      видимості, порядку й щільності. Усе зберігається й переживає
      перезавантаження. Прокрутіть таблицю вбік: колонка SKU лишається на
      місці, решта їде під неї, а кнопка — біля правого краю.
    </p>
  </div>
</template>
```


Кнопка налаштувань не займає ані рядка, ані колонки: вона живе в правому
куті шапки й проявляється, щойно курсор над таблицею. Більшість часу її
ніхто не торкається, і окремий рядок над таблицею заради однієї іконки —
висота, відібрана в даних. Колонка під кнопку була б іще гіршою: порожня
комірка в кожному рядку — мертва смуга вздовж усієї таблиці.

Кут — sticky-елемент тієї самої клітинки сітки, що й таблиця. Він
тримається правого краю видимої області за будь-якої горизонтальної
прокрутки, а з липкою шапкою — ще й верху. Без липкої шапки кнопка їде
вгору разом із нею: налаштування належать шапці, а не рядкам. Під
іконкою — смуга кольору шапки з м'яким краєм, тож заголовок, що
опинився під кутом, згасає, а не перетинається з іконкою.

Прихована до наведення — не означає недосяжна:

- **Клавіатура.** Tab дістає кнопку першою, ще до рядків таблиці, і
  вона проявляється разом із кільцем фокуса.
- **Дотик.** Наведення там не буває, тож кнопку видно завжди, а остання
  колонка шапки віддає їй місце — інакше праворуч вирівняний підпис
  («Сума») назавжди лишився б під іконкою.
- **Схована колонка.** Єдиний стан розкладки, якого не видно в самій
  таблиці: порядок і ширини читаються оком, відсутність — ні. Тому
  кнопка з крапкою, і крапку видно навіть у спокої — вона показує, де
  шукати шлях назад. Колонки, сховані вашими дефолтами (`visible: false`),
  не рахуються: це ваше рішення, а не зміна користувача.

На мобільних картках шапки немає, тож немає й кута: кнопка стає в рядок
над картками, поруч із сортуванням.

Сама панель — спільний компонент із `UiTreeTable`
(`app/components/ui/table/ColumnSettings.vue`), як і арифметика ширин,
порівняння значень при сортуванні й зведення збереженої розкладки
(`app/utils/tableColumns.ts`). Це не економія рядків, а гарантія: дві
копії тієї самої панелі розходяться мовчки й розходилися — у дереві
кнопки порядку мали зону дотику 45×45 і SVG-стрілки, тут лишались
текстові «↑↓» без зони.

## Закріплена перша колонка

`stickyColumn` тримає першу видиму колонку на місці при горизонтальній
прокрутці — той самий контракт, що `stickyTreeColumn` у `UiTreeTable`, і
той самий вигляд: край колонки отримує тінь, щойно під нею починає їхати
вміст. Має сенс лише тоді, коли перша колонка ідентифікує рядок — назва,
SKU, номер; закріплена колонка зі статусом лишає читача без орієнтира.

З `selectable` колонка прапорців теж закріплюється — інакше перша ж
прокрутка ховала б її під колонкою даних.

## Стани


Example (app/demos/table/TableStates.vue):

```vue
<script setup lang="ts">
import { ref } from 'vue'
import UiButton from '~/components/ui/UiButton.vue'
import UiTable, { type TableHeader } from '~/components/ui/UiTable.vue'

const headers: TableHeader[] = [
  { value: 'name', text: 'Назва', width: 200, flex: true },
  { value: 'size', text: 'Розмір', align: 'right', width: 120 },
]

const loading = ref(true)
const items = ref<Record<string, unknown>[]>([])

function loadData() {
  loading.value = true
  items.value = []
  setTimeout(() => {
    items.value = [
      { id: 1, name: 'report.pdf', size: '2.4 МБ' },
      { id: 2, name: 'logo.svg', size: '14 КБ' },
    ]
    loading.value = false
  }, 1200)
}

function loadEmpty() {
  loading.value = true
  items.value = []
  setTimeout(() => (loading.value = false), 900)
}
</script>

<template>
  <div class="w-full space-y-3">
    <div class="flex flex-wrap gap-2">
      <UiButton size="sm" @click="loadData">Завантажити дані</UiButton>
      <UiButton size="sm" variant="outline" @click="loadEmpty">Порожній результат</UiButton>
    </div>
    <UiTable :headers="headers" :items="items" :loading="loading" empty-text="Файлів не знайдено" />
  </div>
</template>

```


## Вибір рядків

`selectable` додає колонку прапорців, `v-model:selected` тримає ключі
обраних рядків. Ключ береться з того самого поля, що вже дає рядкам `:key`
— окремого props для цього немає й не треба.


Example (app/demos/table/TableSelection.vue):

```vue
<script setup lang="ts">
import { ref } from 'vue'
import UiButton from '~/components/ui/UiButton.vue'
import UiChip from '~/components/ui/UiChip.vue'
import UiTable, { type TableHeader } from '~/components/ui/UiTable.vue'
import { useToast } from '~/composables/useToast'

interface Deal extends Record<string, unknown> {
  id: number
  client: string
  status: 'active' | 'won' | 'lost'
  amount: number
  locked?: boolean
}

const toast = useToast()

const headers: TableHeader[] = [
  { value: 'client', text: 'Клієнт', width: 220, flex: true, sortable: true },
  { value: 'status', text: 'Статус', width: 130 },
  { value: 'amount', text: 'Сума', width: 130, align: 'right', sortable: true },
]

const items = ref<Deal[]>([
  { id: 1, client: 'ТОВ «Сігма Трейд»', status: 'active', amount: 420000 },
  { id: 2, client: 'ФОП Коваленко О. П.', status: 'won', amount: 86500 },
  { id: 3, client: 'ПрАТ «Дніпро-Логістик»', status: 'active', amount: 1240000 },
  { id: 4, client: 'ТОВ «Аграрій Плюс»', status: 'lost', amount: 54000, locked: true },
  { id: 5, client: 'ТОВ «Медтехніка»', status: 'active', amount: 315000 },
])

const selected = ref<Array<string | number>>([])

const TONES = { active: 'info', won: 'success', lost: 'danger' } as const
const LABELS = { active: 'В роботі', won: 'Виграно', lost: 'Втрачено' } as const

function formatMoney(value: number) {
  return `${String(Math.round(value)).replace(/\B(?=(\d{3})+(?!\d))/g, ' ')} ₴`
}

function bulkArchive() {
  toast.success(`Заархівовано записів: ${selected.value.length}`)
  selected.value = []
}
</script>

<template>
  <div class="w-full">
    <UiTable
      v-model:selected="selected"
      :headers="headers"
      :items="items"
      key-row="id"
      selectable
      :selectable-row="(item) => !item.locked"
      mobile-cards
    >
      <template #selection-actions="{ clear }">
        <UiButton size="sm" variant="soft" @click="bulkArchive">Заархівувати</UiButton>
        <UiButton size="sm" variant="ghost" @click="clear">Скасувати</UiButton>
      </template>

      <template #cell-status="{ item }">
        <UiChip :tone="TONES[item.status as keyof typeof TONES]" dot>
          {{ LABELS[item.status as keyof typeof LABELS] }}
        </UiChip>
      </template>

      <template #cell-amount="{ item }">
        {{ formatMoney(item.amount as number) }}
      </template>
    </UiTable>

    <p class="mt-3 text-sm text-muted">
      Shift+клік виділяє діапазон. Втрачену угоду обрати не можна —
      <code>selectableRow</code> її виключає.
    </p>
  </div>
</template>

```


Три рішення, які тут неочевидні.

**«Обрати всі» об'єднує, а не замінює.** Таблиця не пагінує сама:
`items` — це вже сторінка, а [`UiPagination`](https://ui.tatet.net/docs/components/pagination)
живе окремо. Якби прапорець у шапці замінював набір, користувач, що вибрав
рядки, перейшов на другу сторінку й натиснув «обрати всі», мовчки втратив
би вибір із першої. Тому шапка додає ключі сторінки до набору й забирає їх
назад — ключі інших сторінок лишаються цілі.

**Shift+клік ставить діапазону стан якоря**, як у Finder і Gmail, а не
перемикає кожен рядок окремо: почергове перемикання дає результат, який
неможливо передбачити оком. Якір — останнє перемикання без Shift. Діапазон
рахується в порядку **показу**, тож після сортування Shift виділяє те, що
видно між двома рядками, а не те, що лежало між ними у вихідних даних.

**Виділення не зберігається.** Ширини й видимість колонок ідуть у
`localStorage`, виділення — ні: набір обраних записів живе рівно стільки,
скільки триває дія над ними.

**Вибір рядків не забороняє копіювати текст.** Раніше `selectable` вішав
`select-none` на всю таблицю — лише щоб Shift+клік не виділяв текст через
пів таблиці, — і з неї не можна було скопіювати жодного номера. Тепер
виділення тексту гаситься тільки на самому жесті Shift+mousedown по
прапорцю.

Сортування виділенню не шкодить: воно ключується по `keyRow`, а не по
індексу, тож перевпорядкування рядків його не плутає.

## API

[Props, events, slots, exposed API (JSON)](https://ui.tatet.net/api/component-meta/UiTable)

## Коли використовувати

Для однорідних даних, які порівнюють між собою по колонках.

`mobileCards` вмикайте завжди, коли колонок більше трьох: горизонтальна
прокрутка таблиці на телефоні — найгірший спосіб читання даних.

Шапки в картках немає, тож сортування живе в окремому рядку над ними:
нативний `<select>` із колонками, що сортуються, і кнопка напрямку. Нативний
— свідомо: телефон відкриває системний вибір, зручніший за будь-яку
випадайку. Рядок з'являється сам, щойно хоч одна видима колонка
`sortable`, і пише в той самий `v-model:sort`.

## Коли НЕ використовувати

Не робіть таблицю з двох колонок «назва / значення» — це список описів
(`<dl>`), і на мобільному він виглядатиме краще без жодних зусиль.

## Ширини живуть у colgroup

`width` — це **число в пікселях**, а не CSS-рядок. Ширини задаються один раз у
`<colgroup>` при `table-layout: fixed`, а не на кожній комірці: за фіксованої
розкладки враховується лише перший рядок, тож інлайновий `width` на кожному
`<td>` був би мертвим стилем, помноженим на кількість рядків.

Рівно одна колонка може мати `flex: true` — вона забирає весь залишок. Сума
фіксованих ширин має вміщатись у контейнер.

Число, а не рядок, ще й тому, що ширина бере участь в арифметиці: ресайз,
збереження, підрахунок переповнення. З `"9rem"` нічого з цього не порахуєш.

## Висота: `maxHeight` чи `fill`

`maxHeight` — стеля в абсолютних одиницях: контейнер обіймає вміст, поки той
нижчий за неї. Працює будь-де, але нічого не знає про сторінку, на якій
стоїть. Типове `max-height: 70vh` під шапкою, фільтрами й пагінацією дає два
дефекти одразу: знизу лишається смуга порожнечі, якої ніщо не заповнює, а
останній рядок ріжеться навпіл там, де до низу екрана ще третина висоти.

`fill` віддає рішення про висоту батьківському контейнеру. Контейнер
прокрутки обіймає вміст, поки той вміщається, і стискається до залишку
висоти, щойно перестав: пагінація під таблицею лишається на екрані, а
таблиця на три рядки не розтягується порожнім тлом на весь екран.

Ціна — ланцюжок. Висота має бути ВИЗНАЧЕНОЮ згори (`h-dvh` на каркасі, не
`min-h-dvh`), а кожна ланка між каркасом і таблицею — flex-колонкою з
`min-h-0`. Пропущений `min-h-0` не дає ані помилки, ані попередження:
елемент просто не стискається, і таблиця тихо рендериться на всю висоту.

```vue
<div class="flex h-dvh flex-col">
  <main class="flex min-h-0 flex-1 flex-col gap-3 overflow-y-auto p-3">
    <section class="flex min-h-96 flex-1 flex-col gap-3">
      <PageHeader />
      <UiTable fill sticky-header :headers="headers" :items="items" />
      <UiPagination v-model:page="page" :total-pages="pages" />
    </section>
  </main>
</div>
```

`min-h-96` на секції — не окраса. Таблиця з `fill` єдина в колонці має
`min-h-0`, тож вона забирає ВЕСЬ дефіцит висоти: у вікні 1280×320 без
підлоги від неї лишається сама шапка. Підлога стоїть на секції, а не на
таблиці, саме тому, що на таблиці вона тримала б порожнечу під короткими
списками; на секції зайва висота йде під пагінацію, де її не видно, а
переповнення бере на себе `overflow-y-auto` на `<main>`.

Саме тому `fill` безпечний і на сторінці, що прокручується: визначеної
висоти згори там немає, стискати немає до чого, і властивість просто знімає
кліть `maxHeight` — таблиця показує всі рядки, а гортає сторінка. Для
таблиці, вбудованої в довгу сторінку, це НЕ завжди те, що треба: якщо
колонки не вміщаються по ширині, горизонтальний скролбар поїде в самий низ
високого блока. Там лишайте `maxHeight`.

## Одне API, дві верстки

Нижче `md` таблиця ховається, а картки рендеряться **з тих самих слотів
`cell-*`**. Розмітку комірки не треба писати двічі:

```vue
<UiTable :headers="headers" :items="items" mobile-cards>
  <template #cell-status="{ item }">
    <UiChip :tone="item.status === 'published' ? 'success' : 'neutral'">
      {{ item.status }}
    </UiChip>
  </template>
</UiTable>
```

## Сортування

Порівняння враховує числа й локаль. Наївні `<` і `>` ставлять «Розділ 10»
перед «Розділ 9», а кирилицю сортують за кодами символів — перевірте це на
прикладі вище.

Порожні значення завжди в кінці, незалежно від напрямку: рядок без даних не
має витісняти заповнені з початку списку.

`Date` порівнюється за часом. Без цього дата падала в рядкове порівняння, і
`toString()` сортував за назвою дня тижня — «Fri» перед «Mon» перед «Thu».
Невалідна дата вважається порожньою.

Коли в комірці не те, що треба порівнювати, задайте колонці `sortValue`:
вкладене поле, код статусу з власним порядком, рядкова дата «24.09.2026».
Значення читається один раз на рядок, а не на кожне порівняння.

```ts
const headers: TableHeader[] = [
  { value: 'author', text: 'Автор', sortable: true, sortValue: (item) => item.author.name },
  { value: 'status', text: 'Статус', sortable: true, sortValue: (item) => STATUS_ORDER[item.status] },
]
```

Тип рядка — звичайний `interface`: обмеження генерика `Record<string, any>`
приймає його без `extends Record<…>`.

Третій клік по заголовку **скидає** сортування. Без цього повернутися до
вихідного порядку можна було б лише перезавантаженням сторінки.

Для серверного сортування задайте `serverSort`: компонент повідомить про
намір через `update:sort`, але порядок рядків не чіпатиме.

## Стани

Скелетон показується лише при **першому** завантаженні. Якщо дані вже є,
замість нього накладається напівпрозорий оверлей — інакше таблиця блимала б
на кожній зміні фільтра.

Ширина заглушок детермінована, а не випадкова: `Math.random()` міняв би її
на кожному рендері, і скелетон миготів би.

Мобільні картки мають ті самі стани: скелетон-картки при першому
завантаженні, оверлей «Оновлення…» при повторному, слот `empty` — коли
даних немає. Раніше телефон показував порожнечу на весь час першого запиту
(скелетон жив у схованій таблиці), а замість слота `empty` — голий
`emptyText`.

## Доступність

Заголовки колонок мають `scope="col"` і `aria-sort`. Сортування вмикається
кнопкою всередині `<th>`, а не кліком по самому `<th>` — інакше воно
недоступне з клавіатури.

`rowClickable` лишає рядок рядком: він потрапляє в Tab-обхід і
активується Enter, Space чи кліком, але БЕЗ `role="button"`. Ця роль на
`<tr>` стирала семантику таблиці — комірки переставали бути пов'язаними із
заголовками, а прапорець і кнопки в комірках опинялися вкладеними в
кнопку, тобто для скрінрідера зникали.

Контроли всередині рядка мають власну дію. Enter чи клік по кнопці або
посиланню в `cell-*` не відкриває рядок — раніше рядок перехоплював Enter
і скасовував активацію самої кнопки. Так само не відкриває рядок виділений
мишею текст: це копіювання, а не клік.

Фокус клікабельного рядка малюється на комірках. Кільце на самому `<tr>`
не було видно ніколи: позиційовані комірки (роздільник, sticky) малюються
поверх тіні рядка разом зі своїм непрозорим тлом.

`stickyHeader` **вимагає** контейнера з власною прокруткою — тобто
`maxHeight` або `fill`. Без жодного з них закріплювати шапку немає відносно
чого, і властивість мовчки нічого не робить.

Кнопка налаштувань ховається через `opacity`, а не `v-if` чи
`visibility`: вона лишається в Tab-обході й у дереві доступності. Мітка
називає кількість схованих колонок — «Налаштування колонок (приховано:
2)», — тож крапку на кнопці чує й скрінрідер. Зона дотику — 45px
завширшки, але обрізана по висоті шапки: у щільній шапці (27px) повна
зона залізла б на 9px у перший рядок, і тап по його правому краю
відкривав би налаштування замість рядка.

## Дві осі версій збереженого

Найтонше місце всієї таблиці. Збережена розкладка має два незалежні номери
версій, бо в ній змішані дві різні речі.

`settingsVersion` — **ваш**. Підніміть його, коли змінили дефолтні ширини чи
видимість у `headers`: збережене більше не описує ту саму таблицю, і тримати
його означало б показувати користувачам чужу розкладку.

`SETTINGS_SCHEMA` — **компонента**. Коли міняється формат payload, порядок і
видимість (це вибір користувача) мігрують уперед, а ширини й щільність (це
дефолти компонента) скидаються.

Нова колонка вставляється **після найближчого лівого сусіда**, а не в кінець.
Без цього колонка, додана через пів року, стрибала б у хвіст у кожного, хто
колись міняв порядок.

`tableId` варто передавати динамічно там, де таблиця показує різні сутності
(`group-${id}`) — компонент стежить і за ним, інакше наступна сутність
відкрилася б із розкладкою попередньої.

## Афорданси прокрутки

Переповнення рахується як `ширина таблиці − ширина видимої області`, а не через
`scrollWidth`. Так градієнт з'являється і після ресайзу колонки — від нього
розмір контейнера не міняється, тож самого `ResizeObserver` було б замало.

`ResizeObserver` при цьому теж потрібен: згортання сайдбара міняє ширину
контейнера без жодної події `resize` вікна.

## Чого тут немає

Віртуального скролу. Для списків у тисячі рядків беріть пагінацію або
серверну фільтрацію. Якщо дані ще й ієрархічні — `TreeTable`: він
віртуалізує рядки, але вимагає фіксованої висоти рядка, якої тут немає.


## Event descriptions

- `update:sort`: Нове сортування або `null`, якщо скинуто. Використовуйте через `v-model:sort`.
- `update:headers`: Розкладка колонок змінилася — видимість, порядок або ширина.
- `rowClick`: Активація рядка кліком, Enter або Space. Лише коли задано `rowClickable`.
- `update:selected`: Ключі обраних рядків. Використовуйте через `v-model:selected`.


[Source files, dependencies and ZIP](https://ui.tatet.net/registry/components/table.json)
