# DescriptionList

Пари «назва — значення» для картки запису, з довільним рендером кожного значення.


Картка клієнта, деталі угоди, підсумок замовлення — усе, що в макеті
виглядає як два стовпчики тексту, а в розмітці має бути `<dl>`.


Example (app/demos/description-list/DescriptionListBasic.vue):

```vue
<script setup lang="ts">
import UiChip from '~/components/ui/UiChip.vue'
import UiDescriptionList, { type DescriptionItem } from '~/components/ui/UiDescriptionList.vue'

const items: DescriptionItem[] = [
  { key: 'company', term: 'Компанія', value: 'ТОВ «Сігма Трейд»' },
  { key: 'status', term: 'Статус' },
  { key: 'manager', term: 'Менеджер', value: 'Олена Ковальчук' },
  { key: 'amount', term: 'Сума угоди', value: '₴420 000' },
  { key: 'created', term: 'Створено', value: '12 серпня 2026' },
  { key: 'source', term: 'Джерело', value: null },
  { key: 'address', term: 'Адреса', value: 'м. Львів, вул. Городоцька 174, офіс 12', wide: true },
]
</script>

<template>
  <div class="w-full max-w-2xl rounded-card border border-line bg-card p-5">
    <UiDescriptionList :items="items" divided>
      <template #value-status>
        <UiChip tone="success" dot>Активний</UiChip>
      </template>
    </UiDescriptionList>
  </div>
</template>

```


## Дві колонки пар, а не назва плюс значення

`grid-cols-2` просто на `<dl>` дає не те, чого від нього чекають: у першу
колонку йдуть усі `<dt>`, у другу — всі `<dd>`. Це inline-розкладка однієї
колонки пар, а не дві колонки.

Дві колонки ПАР вимагають, щоб кожна пара була обгорнута у `<div>` — усередині
`<dl>` це легально з HTML5 — а сітка стояла на самому `<dl>`. Компонент так і
робить; помітити різницю на око майже неможливо, тому вона зафіксована тут.

Поле з `wide: true` займає обидві колонки: адреса чи коментар не мають
ламати ритм решти.


Example (app/demos/description-list/DescriptionListInline.vue):

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

const items: DescriptionItem[] = [
  { key: 'plan', term: 'Тариф', value: 'Команда' },
  { key: 'seats', term: 'Місць', value: '12 із 25' },
  { key: 'renew', term: 'Наступне списання', value: '1 вересня' },
  { key: 'invoice', term: 'Рахунок', value: '№ 2026-0841' },
]
</script>

<template>
  <div class="w-full max-w-sm rounded-card border border-line bg-card p-5">
    <h3 class="mb-3 text-sm font-semibold text-ink">Підписка</h3>
    <!-- inline лишається inline і на телефоні: саме заради цього вигляду
         пару «назва / значення» не роблять таблицею. -->
    <UiDescriptionList :items="items" layout="inline" :columns="1" size="sm" divided />
  </div>
</template>

```


## Значення складніші за текст

Статус — це чип, менеджер — посилання, сума — моноширинне число. Для цього
є слот `value-<key>`, названий за ключем поля, як `cell-*` у
[`UiTable`](https://ui.tatet.net/docs/components/table):

```vue
<UiDescriptionList :items="items">
  <template #value-status>
    <UiChip tone="success" dot>Активний</UiChip>
  </template>
</UiDescriptionList>
```

Порожні значення (`null`, `undefined`, порожній рядок) друкуються як
`emptyText` — типово тире. Порожня клітинка без символа читається як
недомальований інтерфейс, а не як «даних немає».

Довге неподільне значення — URL, IBAN, email — переноситься всередині
своєї пари. Раніше воно виштовхувало `<dd>` за межу картки в
inline-розкладці, а у двох колонках налазило на сусідню пару: і пара, і
значення тепер можуть стискатися (`min-w-0`), а слово, що не вміщається,
рветься (`break-words`) — той самий захист, що в мобільних картках
[`UiTable`](https://ui.tatet.net/docs/components/table).

## API

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

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

- Картка запису: реквізити, контакти, метадані.
- Панель деталей збоку від таблиці.
- Підсумок форми перед підтвердженням.

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

- Для однорідних рядків з однаковими полями — це таблиця
  ([`UiTable`](https://ui.tatet.net/docs/components/table)), і сортування там теж знадобиться.
- Для полів, які редагуються: подивіться на
  [`UiInlineEdit`](https://ui.tatet.net/docs/components/inline-edit).
- Для однієї пари: абзац із жирною назвою простіший і чесніший.

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

Розмітка — справжні `<dl>`, `<dt>`, `<dd>`. Скрінрідери оголошують такий
список як «список описів» і дозволяють переходити між парами; набір
`<div>`ів із класами цього не дає.

Обгортка кожної пари у `<div>` семантику не ламає: HTML5 явно дозволяє
групувати `dt`/`dd` таким чином.


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