# Button

Основна кнопка дії з варіантами, розмірами та станом завантаження.


Кнопка — єдиний компонент, який є в усіх чотирьох вихідних проєктах, і
скрізь написаний по-різному. Ця версія збирає рішення, кожне з яких
закриває конкретний баг.

## Приклад


Example (app/demos/button/ButtonBasic.vue):

```vue
<script setup lang="ts">
import UiButton from '~/components/ui/UiButton.vue'
</script>

<template>
  <UiButton @click="() => {}">Зберегти</UiButton>
</template>

```


## Варіанти

`solid` — головна дія на екрані, і вона має бути одна. Решта — підпорядковані.


Example (app/demos/button/ButtonVariants.vue):

```vue
<script setup lang="ts">
import UiButton from '~/components/ui/UiButton.vue'
</script>

<template>
  <div class="flex flex-wrap items-center gap-3">
    <UiButton variant="solid">solid</UiButton>
    <UiButton variant="soft">soft</UiButton>
    <UiButton variant="tonal">tonal</UiButton>
    <UiButton variant="outline">outline</UiButton>
    <UiButton variant="ghost">ghost</UiButton>
    <UiButton variant="danger">danger</UiButton>
    <UiButton variant="link">link</UiButton>
  </div>
</template>

```


`link` не має ні висоти, ні полів розміру — лише шрифт, — і не стискається
при натисканні: це текст посеред абзацу чи підвалу картки. Розміри для нього
окремі, а не «перекриті» поверх звичайних: `px-0` над `px-4` вирішувався
порядком класів у згенерованому CSS, і Tailwind ставив `.px-0` раніше —
посилання отримувало 11–19px полів з боків.

## Вторинна дія: tonal чи outline

`tonal` — звичайна кнопка для другої дії поруч із головною: «Скасувати» у
вікні, «Назад» у кроках форми, «Пізніше» в банері. Заливка — `ink` під 10%
альфи, без рамки, як типова кнопка GNOME; наведення й натискання — 15% і
20%, ті самі кроки, що в хрестика UiModal і UiDrawer.


Example (app/demos/button/ButtonTonal.vue):

```vue
<script setup lang="ts">
import UiButton from '~/components/ui/UiButton.vue'
</script>

<!--
  Та сама пара «вторинна + головна» на двох поверхнях: картці й кольоровій
  підкладці. Заливка tonal напівпрозора, тож бере відтінок тла — на
  підкладці вона не стає білою коробкою, як outline з непрозорим bg-card.
-->
<template>
  <div class="grid w-full max-w-md gap-4">
    <div class="rounded-card border border-line bg-card p-5 shadow-card">
      <p class="font-semibold text-ink">Опублікувати чернетку?</p>
      <p class="mt-1 text-sm text-muted">Сторінку побачить уся команда.</p>
      <div class="mt-5 flex justify-end gap-3">
        <UiButton variant="tonal">Скасувати</UiButton>
        <UiButton>Опублікувати</UiButton>
      </div>
    </div>

    <div class="flex flex-wrap items-center justify-between gap-3 rounded-card bg-info-bg px-4 py-3">
      <p class="text-sm text-ink">Доступна нова версія.</p>
      <div class="flex gap-2">
        <UiButton variant="tonal" size="sm">Пізніше</UiButton>
        <UiButton size="sm">Оновити</UiButton>
      </div>
    </div>
  </div>
</template>

```


Беріть `tonal` замість `outline`, коли:

- **Кнопка стоїть у футері вікна чи панелі** поруч із `solid` або `danger`.
  Шапки й футери UiModal та UiDrawer пласкі, структуру там тримають
  відступи, а не лінії, і рамка навколо «Скасувати» була останньою
  коробкою у вікні.
- **Тло — не картка.** Заливка напівпрозора і бере відтінок поверхні: тла
  сторінки, кольорового банера, підкладки алерту. `outline` має непрозорий
  `bg-card` і на такому тлі стає окремою білою плиткою.
- **Потрібна однакова вага в обох темах.** На темній картці `outline` має те
  саме тло, що й картка, і тримається лише на тонкій лінії `--line`; 10%
  `ink` читаються однаково на світлому й темному.

`outline` лишайте там, де межа щось означає: кнопка в одному ряду з полями
(рамка вторить рамці поля, і ряд читається як одна панель фільтрів) і
кнопки всередині UiButtonGroup — шви групи складаються з рамок сусідніх
кнопок, накладених через `-ml-px`, і без рамки їх немає з чого зібрати.

## Розміри

Ієрархія зберігається на ОБОХ екранах: `sm` 8 / `md` 9 / `lg` 11 на десктопі,
9 / 10 / 12 на мобільному. Точність дотику тримає не висота, а невидима зона
45×45 навколо кнопки (W3C 2.5.8 Target Size) — вмикається лише на пристрої
з грубим вказівником (`pointer-coarse`), тому на телефоні дрібна `sm`-кнопка
в панелі списку лишається дрібною, але палець у неї влучає.


Example (app/demos/button/ButtonSizes.vue):

```vue
<script setup lang="ts">
import UiButton from '~/components/ui/UiButton.vue'
</script>

<!--
  Усі три розміри поруч: на дотику ієрархія ЗБЕРІГАЄТЬСЯ (9/10/12), а не
  зводиться до однакових 45px, як було раніше. Зону дотику 45×45 демон
  не показує — вона невидима.
-->
<template>
  <div class="flex flex-wrap items-center gap-3">
    <UiButton size="sm" variant="soft">small</UiButton>
    <UiButton size="md" variant="soft">medium</UiButton>
    <UiButton size="lg" variant="soft">large</UiButton>
    <UiButton size="icon" variant="outline" label="Налаштування">
      <svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" aria-hidden="true">
        <path d="M12 15a3 3 0 1 0 0-6 3 3 0 0 0 0 6z" stroke="currentColor" stroke-width="2" />
        <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 1 1-4 0v-.09a1.65 1.65 0 0 0-1-1.51 1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 1 1 0-4h.09a1.65 1.65 0 0 0 1.51-1 1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.65 1.65 0 0 0 1.82.33h.08a1.65 1.65 0 0 0 1-1.51V3a2 2 0 1 1 4 0v.09a1.65 1.65 0 0 0 1 1.51h.08a1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82v.08a1.65 1.65 0 0 0 1.51 1H21a2 2 0 1 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z" stroke="currentColor" stroke-width="2" />
      </svg>
    </UiButton>
    <UiButton size="icon-sm" variant="outline" label="Видалити">
      <svg class="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" aria-hidden="true">
        <path d="M3 6h18M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2m3 0v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
      </svg>
    </UiButton>
  </div>
</template>
```


## Завантаження

Індикатор позиційований абсолютно, а вміст лише гасне до `opacity-0`. Кнопка
не змінює ширину посеред запиту, тож сусідні елементи не стрибають.


Example (app/demos/button/ButtonLoading.vue):

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

const saving = ref(false)

function save() {
  saving.value = true
  setTimeout(() => (saving.value = false), 1800)
}
</script>

<template>
  <div class="flex flex-wrap items-center gap-3">
    <UiButton :loading="saving" @click="save">Зберегти</UiButton>
    <UiButton variant="outline" :loading="saving" @click="save">Ширина не стрибає</UiButton>
  </div>
</template>

```


## API

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

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

Для дій, що щось змінюють: надіслати форму, зберегти, видалити.

Якщо дія веде на іншу сторінку — передайте `to`. Корінь стане `NuxtLink`,
і повернеться середній клік, Ctrl+клік та «відкрити в новій вкладці», яких
у `<button @click="navigateTo(...)">` немає.

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

Не ставте `variant="solid"` двом кнопкам поруч: якщо головні обидві, то
головної немає жодної.

Для кнопок без тексту обов'язковий `label` — інакше кнопка для скрінрідера
безіменна.

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

Фокус-кільце видиме: `focus-visible:ring-2` на токені `--ring`, з
`ring-offset`, який відриває кільце від заливки. У вихідних проєктах
`focus:outline-none` стоїть майже всюди без заміни — керування з
клавіатури там сліпе.

Під час завантаження кнопка отримує `aria-busy`, а кліки блокуються і на
рівні обробника, і атрибутом `disabled`. Індикатор несе прихований текст
«Завантаження»: жива область без тексту, лише з `aria-label`, не мала що
оголосити.


## Event descriptions

- `click`: Клік по кнопці. Не спрацьовує, поки вона `disabled` або `loading`.


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