elixir_uikit

# elixir_uikit — Usage Rules

`elixir_uikit` provides [UIkit 3](https://getuikit.com/) components and LiveView hooks for Phoenix applications. Use these components instead of writing raw UIkit HTML.

## Setup

Run `mix uikit.setup` to configure your project automatically (imports, hooks, CSS).

## Component Quick Reference

### UI Components (`Uikit.Components`)

| Component | Key Attrs | Slots |
|---|---|---|
| `uk_button` | `variant` (`default\|primary\|secondary\|danger\|text\|link`), `size` (`small\|large`), `type`, `disabled`, `uk_toggle` | `inner_block` |
| `uk_badge` | `class` | `inner_block` |
| `uk_card` | `variant` (`default\|primary\|secondary`), `size` (`small\|large`), `hover` | `header`, `body`, `footer` (has `class`), `close`, `inner_block` |
| `uk_card_title` | `class` | `inner_block` |
| `uk_container` | `size` (`xsmall\|small\|large\|xlarge\|expand`) | `inner_block` |
| `uk_section` | `variant` (`default\|muted\|primary\|secondary`), `size` (`xsmall\|small\|large\|xlarge\|remove-vertical`) | `inner_block` |
| `uk_grid` | `gap` (`small\|medium\|large\|collapse`), `divider`, `match`, `masonry` | `inner_block` |
| `uk_sortable` | `id` (required), `group`, `handle`, `grid`, `animation`, `threshold`, `cls_custom` | `inner_block` |
| `uk_icon` | `name` (required), `ratio`, `button` | — |
| `uk_modal` | `id` (required), `center`, `container` (default `false`), `full`, `esc_close`, `bg_close`, `stack`, `show`, `on_close` | `header`, `body`, `footer` (has `class`), `close`, `inner_block` |
| `uk_modal_title` | `class` | `inner_block` |
| `uk_label` | `variant` (`success\|warning\|danger`) | `inner_block` |
| `uk_spinner` | `ratio` | — |
| `uk_subnav` | `id` (required), `divider`, `pill`, `switcher`, `active`, `on_change` | `item` (has `href`, `active`, `disabled`, `class`) |
| `uk_switcher` | `id` (required), `animation` | `inner_block` |

### Form Components (`Uikit.FormComponents`)

| Component | Key Attrs | Slots |
|---|---|---|
| `uk_form` | `for` (required), `id` (required), `layout` (`stacked\|horizontal`) | `inner_block` |
| `uk_input` | `field`, `type` (text/email/select/textarea/etc.), `label`, `size`, `width`, `state`, `blank`, `options`, `prompt`, `multiple` | — |
| `uk_checkbox` | `field`, `label`, `value`, `checked`, `state` | — |
| `uk_radio` | `field`, `label`, `value` (required), `checked`, `state` | — |
| `uk_range` | `field`, `label`, `value` | — |
| `uk_fieldset` | `class` | `legend`, `inner_block` |
| `uk_form_label` | `for`, `class` | `inner_block` |
| `uk_form_controls` | `text` | `inner_block` |
| `uk_form_icon` | `icon` (required), `flip`, `clickable` | `inner_block` |

## LiveView Hooks

Three hooks are exported from `elixir_uikit`: **Sortable**, **Modal**, **Switcher**. See [usage-rules/hooks.md](usage-rules/hooks.md) for details.

## Common Patterns

See [usage-rules/patterns.md](usage-rules/patterns.md) for cards in grids, forms with validation, server-controlled modals, and tab navigation.

## UIkit CSS Utilities

See [usage-rules/css-utilities.md](usage-rules/css-utilities.md) for `uk-*` utility classes (layout, text, spacing, visibility, flex).

## Do's and Don'ts

**Do:**
- Always use `container: false` (the default) on modals — this keeps the modal in the LiveView DOM tree so LiveView can patch it.
- Always provide stable `id` attributes on `uk_sortable`, `uk_subnav`, `uk_switcher`, and `uk_modal` elements. Child items of sortable containers must also have unique IDs.
- Use `uk_button` with `navigate` or `patch` for navigation instead of raw `<a>` tags.
- Use `field={@form[:field_name]}` on form components for automatic ID, name, value, and error handling.
- Use `<.uk_checkbox>` for checkboxes (not `uk_input` with `type="checkbox"`) — it handles the hidden false-value field.

**Don't:**
- Don't set `container: true` on modals in LiveView — UIkit will move the modal outside the LiveView DOM tree, breaking patching.
- Don't use raw UIkit HTML when a component exists — the components handle class generation and LiveView integration.
- Don't forget `id` on interactive components (`uk_sortable`, `uk_subnav` with switcher, `uk_modal` with `show`).
- Don't use `uk_input` with `type="checkbox"` — use `uk_checkbox` instead.