# Frappe UI Phx
[](https://github.com/moacirbishopcamata/frappe_ui_phx/actions/workflows/ci.yml)
Componentes **Phoenix LiveView** com a identidade visual do [Frappe UI](https://ui.frappe.io): os mesmos
design tokens (`surface-*`, `ink-*`, `outline-*`, modo escuro), o mesmo markup e as mesmas classes, **sem Vue**.
O estado fica no servidor; JavaScript só aparece onde `Phoenix.LiveView.JS` e o HTML nativo não chegam
(hooks *colocated*, ao lado do componente).
> **Projeto independente, não oficial.** Não é mantido nem endossado pela Frappe Technologies.
- **78 componentes** em 8 categorias, mais blocos internos: formulários, feedback, overlays, navegação e layout, dados,
charts (SVG gerado no servidor), moléculas e experimentais.
- **Ícones Lucide**: todos os ~2.000, como componentes (``), com `size`, `color` e `stroke_width`.
- **Fundamentos**: cores, tipografia, raio, sombras, anel de foco e cores de gráficos.
- **Integrações**: Ecto (tipos e erros), Plug (tema) e LiveView (toasts, diálogos, ordenação).
- **Mostruário navegável** com *playground* gerado dos `attr` reais e a especificação de cada componente.
Índice: [Instalação](#instalação) · [Primeiros passos](#primeiros-passos) · [Convenções](#convenções-que-valem-para-todos-os-componentes) ·
[Formulários](#formulários) · [Feedback](#feedback-e-exibição) · [Overlays](#overlays) · [Navegação](#navegação-e-layout) ·
[Dados](#dados-listas-árvores-e-ordenação) · [Charts](#charts) · [Moléculas](#moléculas-e-experimentais) · [Ícones](#ícones-lucide) ·
[PinCode e DiceBear](#pincode-e-dicebearavatar) · [Tema](#tema-claro-e-escuro) · [Ecto e Plug](#integrações-ecto-e-plug) ·
[Configuração](#configuração) · [Solução de problemas](#solução-de-problemas) · [Referência completa](docs/componentes.md)
---
## Instalação
### Requisitos
| Item | Versão |
|---|---|
| Elixir | `~> 1.18` |
| Phoenix | `~> 1.8` |
| Phoenix LiveView | `~> 1.2` (hooks *colocated* exigem LiveView ≥ 1.1) |
| Tailwind | v4 (é o padrão de um app `mix phx.new` 1.8) |
| Navegador | recente: Popover API e CSS Anchor Positioning (Dropdown, Popover, DatePicker, MultiSelect) |
O app precisa ter `compilers: [:phoenix_live_view] ++ Mix.compilers()` no `mix.exs` — já vem assim num app novo do Phoenix 1.8.
### 1. Adicione a dependência
```elixir
# mix.exs
defp deps do
[
# a) do GitHub (hoje o repositório é privado: exige acesso à conta)
{:frappe_ui_phx,
git: "https://github.com/moacirbishopcamata/frappe_ui_phx.git", branch: "worktree-componentes-fase1"},
# b) de uma pasta local
# {:frappe_ui_phx, path: "../frappe_ui_phx"},
# c) do Hex, depois de publicado
# {:frappe_ui_phx, "~> 0.3"}
]
end
```
```sh
mix deps.get
```
A primeira compilação demora (~35 s): o módulo `FrappeUIPhx.Icons.Lucide` tem um componente para cada ícone. Acontece uma vez.
### 2. Rode o instalador
```sh
mix frappe_ui_phx.install --dry-run # mostra o que faria, sem escrever nada
mix frappe_ui_phx.install # aplica; é idempotente (pode rodar de novo)
```
O instalador:
| Arquivo | O que muda |
|---|---|
| `assets/css/app.css` | importa `frappe_ui.css` (tokens) e adiciona `@source` para os componentes, logo depois de `@import "tailwindcss"` |
| `assets/js/app.js` | importa os hooks *colocated* da biblioteca e os soma ao `hooks:` do `LiveSocket` |
| `mix.exs` | **só verifica** o `compilers:`; não altera |
Opções: `--dry-run` e `--dep-path CAMINHO` (padrão: onde o Mix achou a dependência). Uma opção desconhecida (por exemplo
`--dryrun`) aborta sem escrever nada.
### 3. Equivalente manual (se preferir, ou se o instalador não reconhecer seu `app.css`)
```css
/* assets/css/app.css */
@import "tailwindcss" source(none);
@source "../css";
@source "../js";
@source "../../lib/my_app_web";
@import "../../deps/frappe_ui_phx/priv/static/frappe_ui.css"; /* tokens, tema, utilitários */
@source "../../deps/frappe_ui_phx/lib"; /* o Tailwind precisa enxergar as classes dos componentes */
```
```js
// assets/js/app.js
import {hooks as colocatedHooks} from "phoenix-colocated/my_app"
import {hooks as frappeUiHooks} from "phoenix-colocated/frappe_ui_phx"
const liveSocket = new LiveSocket("/live", Socket, {
params: {_csrf_token: csrfToken},
hooks: {...colocatedHooks, ...frappeUiHooks},
})
```
> Em um app Phoenix 1.8, `phoenix-colocated/...` já resolve pelo `NODE_PATH` da configuração do esbuild gerada pelo `mix phx.new`.
### 4. Importe os componentes
```elixir
# lib/my_app_web.ex
defp html_helpers do
quote do
# ... imports que já existem (CoreComponents, Phoenix.HTML...)
use FrappeUIPhx, except: [button: 1, icon: 1, list: 1]
end
end
```
`use FrappeUIPhx` importa as funções de componente do catálogo (`<.badge>`, `<.alert>`, `<.dialog>`...) e
`show_dialog/1`/`hide_dialog/1`.
**Colisões de nome.** O `CoreComponents` gerado pelo Phoenix já define `button/1`, `icon/1`, `list/1` (e `input`, `table`, `header`, `flash`...).
Duas formas de resolver:
```elixir
use FrappeUIPhx, except: [button: 1, icon: 1, list: 1] # importa tudo, menos estes
use FrappeUIPhx, only: [badge: 1, alert: 1, dialog: 1] # importa só o que você usa
```
Os excluídos continuam acessíveis com o módulo: ``.
Um nome desconhecido em `only:`/`except:` falha na compilação, listando os nomes válidos.
### 5. Tema, toasts e layout
```elixir
# lib/my_app_web/router.ex
pipeline :browser do
# ... plugs existentes
plug :fetch_session
plug FrappeUIPhx.Plug.Theme # resolve ?theme=dark → sessão → cookie → "light"
end
scope "/", MyAppWeb do
pipe_through :browser
live_session :default, on_mount: [FrappeUIPhx.Live.ThemeHook] do
live "/", HomeLive
end
end
```
```heex
<%!-- lib/my_app_web/components/layouts/root.html.heex --%>
```
```heex
<%!-- lib/my_app_web/components/layouts.ex (app/1) ou no layout da página --%>
<.toast_container flash={@flash} />
```
> **Atenção com o tema do Phoenix 1.8.** O root layout gerado costuma controlar `data-theme` (daisyUI) com um pequeno script e
> `localStorage`. Se você usar o `FrappeUIPhx.Plug.Theme`, remova esse script ou mantenha **um só dono** do atributo `data-theme`
> (os dois brigando produzem tema que "pisca"). Valores aceitos: `"light"` e `"dark"`.
Tema padrão diferente de claro: `plug FrappeUIPhx.Plug.Theme, default: "dark"` e `on_mount: [{FrappeUIPhx.Live.ThemeHook, default: "dark"}]`.
> O CSS do Frappe UI **não substitui** as escalas padrão do Tailwind (cores, `text-sm`, sombras): os tokens entram em namespaces
> próprios (`bg-surface-*`, `text-ink-*`, `border-outline-*`, `fui-text-*`, `shadow-elevation-*`), então o daisyUI e as classes do seu app continuam intactos.
### 6. Confira
Crie uma LiveView (ou edite a `HomeLive`) com:
```heex
<.alert theme={:green} title="Instalado">frappe_ui_phx está funcionando.
<.button label="Salvar" variant={:solid} icon_left="check" />
<.badge label="Novo" theme={:blue} />
```
Se os estilos não aparecerem, veja [Solução de problemas](#solução-de-problemas).
---
## Primeiros passos
Um componente é uma *function component* comum do Phoenix: atributos como `attr`, conteúdo como slots.
```heex
<.button label="Enviar" variant={:solid} theme={:blue} size={:md} phx-click="enviar" />
<.alert theme={:amber} title="Atenção">
O prazo termina amanhã.
<:actions><.button label="Ver detalhes" size={:xs} />
<.dropdown id="acoes" label="Ações">
<:item label="Editar" icon="pencil" click="editar" />
<:item label="Abrir página" navigate={~p"/pedidos"} />
<:item label="Excluir" icon="trash-2" theme={:red} click="excluir" />
```
## Convenções que valem para todos os componentes
- **Variantes, temas e tamanhos são átomos**: `variant={:solid}`, `theme={:red}`, `size={:sm}`. Os valores aceitos aparecem na
[referência](docs/componentes.md) e no mostruário. Valor fora da lista **levanta `ArgumentError`** com a lista válida
(falha alto em vez de renderizar errado em silêncio).
- **Atributos globais**: todo componente com elemento raiz repassa `class`, `id`, `data-*`, `aria-*` e `phx-*` (`phx-click`, `phx-hook`...).
`class` é somado às classes do componente.
- **`id` obrigatório** nos componentes que têm estado de UI ou hook (`dialog`, `bottom_sheet`, `dropdown`, `popover`, `context_menu`, `tabs`, `date_picker`, `combobox`, `multi_select`, `password`,
`pin_code`, `editor`, `code_editor`, `list`, `list_view`, `tree`, `sortable`, `accordion`, `calendar`, `command_palette`...).
O `id` vira seletor e é validado: precisa ser um identificador CSS simples (letras, números, `-`, `_`).
- **Campos de formulário** aceitam `field={@form[:campo]}` (nome, id, valor e erros vêm do `Phoenix.HTML.FormField`) **ou** `name`/`value` avulsos.
Erros de changeset só aparecem depois que o campo foi usado (`used_input?/1`), como no `CoreComponents` do Phoenix.
- **Eventos**: atributos `on_*` / `click` recebem o **nome do evento** do servidor (`on_select="sel"`). Slots de item aceitam `navigate`, `patch`,
`href` (links) ou `click` (evento, ou um comando `JS`).
- **Entrada de usuário nunca levanta.** Contrato (`ArgumentError`) vale para quem escreve o template; o que o usuário digita vira `errors`, e
eventos forjados do cliente (uma data fora de `min`/`max`, um id que não existe) são ignorados.
- **Ícones** são nomes Lucide em string (`icon="plus"`, `icon_left="chevron-right"`). Veja [Ícones Lucide](#ícones-lucide).
- **Textos fixos** ("Fechar", "Mês anterior"...) são configuráveis. Veja [Configuração](#configuração).
Referência de **todos** os atributos, tipos, padrões e slots: [`docs/componentes.md`](docs/componentes.md) (gerada do código).
---
## Formulários
### Um formulário completo com Ecto
```elixir
defmodule MyApp.Pedidos.Pedido do
use Ecto.Schema
import Ecto.Changeset
schema "pedidos" do
field :cliente, :string
field :prioridade, Ecto.Enum, values: [:baixa, :media, :alta]
field :entrega, :date
field :observacoes, :string
field :urgente, :boolean, default: false
field :codigo, :string, virtual: true
end
def changeset(pedido, attrs) do
pedido
|> cast(attrs, [:cliente, :prioridade, :entrega, :observacoes, :urgente, :codigo])
|> validate_required([:cliente, :prioridade])
|> validate_length(:cliente, min: 3)
end
end
```
```elixir
defmodule MyAppWeb.PedidoLive do
use MyAppWeb, :live_view
alias MyApp.Pedidos.Pedido
alias FrappeUIPhx.Ecto.Options
def mount(_params, _session, socket) do
{:ok,
socket
|> assign(:prioridades, Options.from_enum(Pedido, :prioridade))
|> assign_form(Pedido.changeset(%Pedido{}, %{}))}
end
def handle_event("validar", %{"pedido" => params}, socket) do
form = %Pedido{} |> Pedido.changeset(params) |> Map.put(:action, :validate) |> to_form()
{:noreply, assign(socket, :form, form)}
end
def handle_event("salvar", %{"pedido" => params}, socket) do
case MyApp.Pedidos.criar(params) do
{:ok, _pedido} ->
{:noreply, FrappeUIPhx.Toast.put_toast(socket, :success, "Pedido salvo!")}
{:error, changeset} ->
{:noreply, assign_form(socket, changeset)}
end
end
defp assign_form(socket, changeset), do: assign(socket, :form, to_form(changeset))
def render(assigns) do
~H"""
<.form for={@form} phx-change="validar" phx-submit="salvar" class="max-w-md space-y-4">
<.form_control field={@form[:cliente]} label="Cliente" required placeholder="Nome do cliente" />
<.form_control field={@form[:prioridade]} label="Prioridade" type="select" options={@prioridades} prompt="Escolha…" required />
<.date_picker id="entrega" field={@form[:entrega]} min={Date.utc_today()} />
<.form_control field={@form[:observacoes]} label="Observações" type="textarea" />
<.checkbox field={@form[:urgente]} label="Urgente" />
<.button type="submit" label="Salvar" variant={:solid} theme={:blue} />
"""
end
end
```
`form_control` junta rótulo + controle + descrição + erros e escolhe o controle pelo `type`: `"text"` (e os demais tipos de ``),
`"textarea"`, `"select"`, `"checkbox"`, `"switch"`. O `required` aqui **espelha** o `validate_required` do changeset — o servidor continua sendo a barreira real.
### Os controles, um a um
```heex
<%!-- Texto --%>
<.text_input name="busca" value="" type="search" placeholder="Buscar…" />
<.textarea name="obs" value="" placeholder="Escreva…" />
<.password field={@form[:senha]} id="senha" /> <%!-- botão de mostrar/ocultar; o valor nunca volta ao HTML --%>
<%!-- Escolha --%>
<.select name="uf" value="SP" options={[{"São Paulo", "SP"}, {"Rio", "RJ"}]} prompt="UF" />
<.combobox id="fruta" name="fruta" value="uva" options={[{"Maçã", "maca"}, {"Uva", "uva"}]} /> <%!-- com busca --%>
<.multi_select id="frutas" name="frutas" value={["maca", "uva"]} options={[{"Maçã", "maca"}, {"Uva", "uva"}]} />
<.radio_group name="plano" value="pro" label="Plano" options={[{"Básico", "basico"}, {"Pro", "pro"}]} />
<.checkbox name="aceito" label="Aceito os termos" />
<.switch name="notificacoes" label="Receber notificações" />
<%!-- Números e tempo --%>
<.slider name="volume" value={40} show_value />
<.rating name="nota" value={3} />
<.date_picker id="data" name="data" value="2026-03-09" /> <%!-- LiveComponent: exige id --%>
<.time_picker name="hora" value="08:30" />
<.duration name="tempo" value={5400} /> <%!-- "1h 30m" ⇄ segundos --%>
<%!-- Arquivos (upload do LiveView) --%>
<.file_uploader upload={@uploads.anexos} on_cancel="cancelar-upload">
<:hint>PNG, JPG ou PDF — até 2 arquivos
```
- **Button** aceita `variant` (`:solid | :subtle | :outline | :ghost`), `theme` (`:gray | :blue | :green | :red`), `size` (`:xs`…`:lg`),
`icon_left`, `icon_right`, `icon` (botão só com ícone), `loading`/`loading_text` e vira link com `href`, `navigate` ou `patch`.
- **Select/MultiSelect/Combobox**: `options` aceita lista de textos, `{rótulo, valor}` ou keyword. `FrappeUIPhx.Ecto.Options.from_enum/2` monta as opções de um `Ecto.Enum`.
- **`Duration`** entende `"1h 30m"`, `"1:30"` e `"90m"`; o tipo Ecto `FrappeUIPhx.Ecto.Duration` guarda segundos.
- **Upload**: o `file_uploader` mostra progresso, cancelamento e os erros do LiveView (tamanho, tipo, quantidade) traduzidos.
> `pin_code` está em [PinCode e DiceBearAvatar](#pincode-e-dicebearavatar).
---
## Feedback e exibição
```heex
<.badge label="Ativo" theme={:green} /> <%!-- :gray :blue :green :amber :red :violet --%>
<.alert theme={:red} title="Falha ao salvar">Tente novamente em instantes.
<.progress value={40} label="Envio" show_value />
<.skeleton class="h-4 w-40" />
<.spinner />
<.loading_text />
<.avatar label="Ana" image={@user.foto_url} size={:lg} shape={:circle} />
<.keyboard_shortcut keys={["Ctrl", "K"]} />
<.error_message message={["Campo obrigatório", "Mínimo de 3 caracteres"]} />
<.saved_indicator at={@saved_at} /> <%!-- novo valor de `at` a cada salvamento reinicia a animação --%>
```
`item_list_row` é uma linha com ícone, título, subtítulo e ações (navegável com `navigate`/`patch`/`href`):
```heex
<.item_list_row title="Contrato.pdf" subtitle="2,1 MB · ontem">
<:icon><.icon name="file-text" />
<:actions><.button label="Abrir" size={:xs} />
```
### Toasts (mensagens do servidor)
Coloque `<.toast_container flash={@flash} />` uma vez no layout. Em qualquer LiveView:
```elixir
FrappeUIPhx.Toast.put_toast(socket, :success, "Salvo!") # :info | :success | :warning | :error
FrappeUIPhx.Toast.put_toast(socket, :error, "Falhou", timeout: 8_000) # padrão: 4000 ms
```
O container também mostra as mensagens do `flash` (`put_flash`). Tipo desconhecido, mensagem vazia ou `timeout` não positivo levantam `ArgumentError`.
Para mudar o transporte, implemente o behaviour `FrappeUIPhx.ToastSink` (veja [Configuração](#configuração)).
---
## Overlays
### Dialog e folha inferior
O `