02 · Actions

Fab

Retractable: retract hover · auto · never · always · expanded · color assistant/primary/dark/light · size · badge · position · variant canvas

A floating action button that retracts: a pill with the icon on a disc and the label, shrinking to just the bubble when not in use.

Motion — retract="hover": the cursor passes and the pill opens (loop)

.heex
<div class="grid grid-cols-3 gap-4"><div class="relative h-[170px] overflow-hidden rounded-[16px] border border-line bg-tray"><.fab id="fab-1" label="Pergunte ao assistente" variant="pill" fixed={false} loop><:icon><.icon name="sparkles" size="md" /></:icon></.fab></div><div class="relative h-[170px] overflow-hidden rounded-[16px] border border-line bg-tray"><.fab id="fab-2" label="Nova fatura" variant="pill" fixed={false} color="primary" retract="auto" loop><:icon><.icon name="plus" size="md" /></:icon></.fab></div><div class="relative h-[170px] overflow-hidden rounded-[16px] border border-line bg-tray"><.fab id="fab-3" label="Chat com a equipe" variant="pill" fixed={false} color="light" loop badge={3}><:icon><.icon name="chat" size="md" /></:icon></.fab></div></div>

retract="hover" — hover over it

.heex
<div class="relative h-[150px] overflow-hidden rounded-[16px] border border-line bg-tray"><.fab id="fab-4" label="Pergunte ao assistente" variant="pill" fixed={false}><:icon><.icon name="sparkles" size="md" /></:icon></.fab></div>

retract="auto" — collapses on its own in 4s

.heex
<div class="relative h-[150px] overflow-hidden rounded-[16px] border border-line bg-tray"><.fab id="fab-5" label="Precisa de ajuda?" variant="pill" fixed={false} retract="auto"><:icon><.icon name="help" size="md" /></:icon></.fab></div>

retract="never" · color="primary"

.heex
<div class="relative h-[150px] overflow-hidden rounded-[16px] border border-line bg-tray"><.fab id="fab-6" label="Nova fatura" variant="pill" fixed={false} color="primary" retract="never"><:icon><.icon name="plus" size="md" /></:icon></.fab></div>

retract="always" · color="light" · badge · bottom-left

.heex
<div class="relative h-[150px] overflow-hidden rounded-[16px] border border-line bg-tray"><.fab id="fab-7" label="Chat com a equipe" variant="pill" fixed={false} color="light" retract="always" position="bottom-left" badge={3}><:icon><.icon name="chat" size="md" /></:icon></.fab></div>

color (expanded)

.heex
<div class="flex flex-wrap items-center gap-3.5"><.fab id="fab-8" label="Assistente" variant="pill" retract="never" static><:icon><.icon name="sparkles" size="md" /></:icon></.fab><.fab id="fab-9" label="Primary" variant="pill" color="primary" retract="never" static><:icon><.icon name="plus" size="md" /></:icon></.fab><.fab id="fab-10" label="Dark" variant="pill" color="dark" retract="never" static><:icon><.icon name="plus" size="md" /></:icon></.fab><.fab id="fab-11" label="Light" variant="pill" color="light" retract="never" static><:icon><.icon name="plus" size="md" /></:icon></.fab></div>

size md · lg · expanded={true}

.heex
<div class="relative h-[150px] overflow-hidden rounded-[16px] border border-line bg-tray"><.fab id="fab-12" label="Médio" variant="pill" fixed={false} color="dark" retract="never" position="bottom-left"><:icon><.icon name="plus" size="md" /></:icon></.fab><.fab id="fab-13" label="Grande" variant="pill" fixed={false} size="lg" expanded><:icon><.icon name="sparkles" size="md" /></:icon></.fab></div>

variant="canvas" (label always visible)

.heex
<div class="relative h-[150px] overflow-hidden rounded-[16px] border border-line bg-tray"><.fab id="fab-canvas" label="Novo pedido" fixed={false}><:icon><.icon name="plus" size="md" /></:icon></.fab></div>

API values that complete the parity

position=bottom-right
position=top-right
position=top-left
.heex
<div class="grid grid-cols-3 gap-3.5"><div class="flex flex-col items-start gap-1.5"><div class="relative h-[120px] w-full rounded-[12px] bg-sunken inset-ring-1 inset-ring-line"><span class="absolute grid size-10 place-items-center rounded-[12px] bg-inverse text-on-inverse shadow-md bottom-2.5 right-2.5"><.icon name="plus" size="md" /></span></div><span class="font-mono text-[11px] text-muted">position=bottom-right</span></div><div class="flex flex-col items-start gap-1.5"><div class="relative h-[120px] w-full rounded-[12px] bg-sunken inset-ring-1 inset-ring-line"><span class="absolute grid size-10 place-items-center rounded-[12px] bg-inverse text-on-inverse shadow-md top-2.5 right-2.5"><.icon name="plus" size="md" /></span></div><span class="font-mono text-[11px] text-muted">position=top-right</span></div><div class="flex flex-col items-start gap-1.5"><div class="relative h-[120px] w-full rounded-[12px] bg-sunken inset-ring-1 inset-ring-line"><span class="absolute grid size-10 place-items-center rounded-[12px] bg-inverse text-on-inverse shadow-md top-2.5 left-2.5"><.icon name="plus" size="md" /></span></div><span class="font-mono text-[11px] text-muted">position=top-left</span></div></div>

Usage

<.fab id="ask" label="Pergunte ao assistente" phx-click="open_assistant" />
<.fab id="help" label="Precisa de ajuda?" retract="auto" retract_after={6000} />
<.fab id="new" label="Nova fatura" retract="never" color="primary" />
<.fab id="chat" label="Chat" retract="always" color="light" position="bottom-left" badge={3} />
<.fab id="new" label="Novo pedido" variant="canvas" offset={18} />

Rules

  • hover (default): a bubble at rest, expands on hover and keyboard focus.
  • auto: starts expanded and collapses after retract_after ms (4000) or on scroll; expands again on hover.
  • never: always expanded. always: always a bubble; the label becomes aria-label and a native tooltip.
  • expanded forces the pill open (an onboarding hint). On touch, every mode but never is a bubble and the tap runs directly.
  • variant="canvas" is the solid inverse button with radius 18 and an always-visible label; variant="pill" is the retractable pill.
  • Sits below modals/drawers and above the page (--ledger-z-fab, 90).

API reference

Todos os function components, atributos, valores e slots que este componente cobre.

Floating action buttons: fab/1, one button (the canvas's solid ink button, or the retracting pill) and fab_dial/1, a speed-dial that opens a column of actions. Styled only with Tailwind utilities.

<.fab id="new" label="Novo pedido" phx-click="new_order">
  <:icon><.icon name="plus" size="md" /></:icon>
</.fab>
<.fab id="ask" label="Pergunte ao assistente" variant="pill" phx-click="open_assistant" />
<.fab id="help" label="Precisa de ajuda?" variant="pill" retract="auto" retract_after={6000} />
<.fab id="chat" label="Chat" variant="pill" retract="always" color="light" position="bottom-left" badge={3} />

<.fab_dial id="quick" label="Ações rápidas">
  <:action label="Novo contato" phx-click="new_contact"><.icon name="user-plus" /></:action>
  <:action label="Enviar arquivo" phx-click="upload"><.icon name="upload" /></:action>
</.fab_dial>

Position

Both are fixed to the viewport corner (fixed, the default; --ledger-z-fab, 90, keeps them under modals and drawers). fixed={false} leaves them absolute in the nearest positioned ancestor, which is how the showcase demos show them inside a box. offset moves a button from its corner, in pixels (18 by default). loop plays the canvas demo loop (the pill opens and closes, the dial opens and closes), for showcases.

Hooks

  • LedgerUI.Fab (priv/static/ledger_ui/hooks/fab.js), only for retract="auto": expands the pill, retracts it after retract_after ms or on scroll, expands it again on hover and focus. data-state is kept across patches (keep-data-state); the utilities read it (data-[state=expanded]:).
  • LedgerUI.FabDial (priv/static/ledger_ui/hooks/fab_dial.js): click toggles, Escape closes and returns focus, arrows/Home/End walk the actions, a click outside or focus leaving closes it.

<.fab>

Attr Type Default Values / notes
id (required) :string
label (required) :string Always rendered, and the aria-label.
position :string "bottom-right" bottom-right, bottom-left, top-right, top-left
color :string "assistant" assistant, primary, dark, light
size :string "md" md, lg
variant :string "canvas" canvas, pill
offset :integer nil Distance from the corner, in pixels.
retract :string "hover" hover, auto, never, always
retract_after :integer 4000 Milliseconds before retract="auto" retracts.
expanded :boolean false Forces the pill open, whatever retract says.
badge :any nil A count or short text on the bubble's corner.
static :boolean false In the flow (relative, no corner, no offset): a sample inside a page or a box.
fixed :boolean true Fixed to the viewport (false: absolute in its parent).
loop :boolean false variant="pill": plays the open/close loop of the canvas demo.
type :string "button"
disabled :boolean false
class :any nil
style :string nil

Any other HTML/phx attribute goes to the root element, including href, navigate, patch, method, download, target, rel, replace, form, name, value.

Slots:

  • <:icon> - The glyph (a sparkle by default).
  • <:inner_block> - Replaces the visible label text (label stays the aria-label).

<.fab_dial>

Attr Type Default Values / notes
id (required) :string
label (required) :string The button's aria-label and the name of the menu.
position :string "bottom-right" bottom-right, bottom-left, top-right, top-left
color :string "primary" assistant, primary, dark, light - Kept for API parity with fab/1.
size :string "md" md, lg - Kept for API parity with fab/1.
variant :string "canvas" canvas, pill
offset :integer nil
open :boolean false The initial state; after mount the hook owns it.
static :boolean false In the flow (relative, no corner, no offset): a sample inside a page or a box.
fixed :boolean true Fixed to the viewport (false: absolute in its parent).
loop :boolean false Plays the open/close loop of the canvas demo.
class :any nil
style :string nil

Any other HTML/phx attribute goes to the root element.

Slots:

  • <:action> (required) - attrs: label (required), href, navigate, patch, phx-click, phx-target, disabled, class - A mini action: the icon is its content.
  • <:icon> - The glyph of the button, a plus by default; it turns while open.