JS Events
Every PhxShadcn interactive component exposes a consistent JS event API.
Components can be controlled imperatively via vanilla JS, talk to each other
through CustomEvents, or be commanded from the server via
push_event/3. Works with Alpine, Stimulus, or
any other JS library.
How It Works
Three communication channels are available on every interactive component.
Dispatch events to a component element to control it imperatively.
Event names use imperative verbs:
open,
close,
press,
select,
toggle.
// Vanilla JS helpers (import + attach to window)
PhxShadcn.open("my-collapsible", "_")
PhxShadcn.press("my-toggle")
PhxShadcn.select("my-group", "A")
// Or use raw CustomEvents directly
el.dispatchEvent(new CustomEvent("phx-shadcn:open", {
detail: { value: "_" }
}))
Components emit events after state changes. Event names use past tense:
opened,
closed,
pressed,
selected.
These don't bubble — listen directly on the component element.
el.addEventListener("phx-shadcn:pressed", (e) => {
console.log(e.detail) // { id: "my-toggle", pressed: true }
})
The server can push commands to any component via
push_event/3
using the phx_shadcn:command channel.
Target components by their id.
push_event(socket, "phx_shadcn:command", %{
id: "my-collapsible",
command: "open",
value: "_"
})Component ↔ Component
A Toggle and a Collapsible wired together purely through outbound → inbound CustomEvents. Pressing the Toggle opens the Collapsible. Opening the Collapsible presses the Toggle. No server round-trips involved.
Vanilla JS Control Panel
Plain JavaScript buttons control components via
PhxShadcn.* helpers.
No LiveView, no Phoenix — just vanilla
onclick handlers.
ToggleGroup (client-only)
Accordion (client-only, collapsible)
Listening to Outbound Events
A Toggle and a Collapsible emit outbound CustomEvents. A pure-JS event log below captures them in real-time — no server round-trip.
External JS → Server-Controlled
Inbound CustomEvents work even on server-controlled components.
When JS dispatches phx-shadcn:press,
the hook detects server mode, calls notifyServer,
which triggers handle_event/3, updates the assign,
and re-renders. The full round-trip confirms the state below.
Vanilla JS buttons (drive server state)
false
Server → Client Push
push_event/3 commands multiple client-mode components
at once from a single server button click. Both the Collapsible and Toggle below
are client-only — no open or
pressed assigns.
Event Reference
All inbound and outbound CustomEvents. Every event is prefixed with
phx-shadcn:.
| Component | Inbound Events | Outbound Events |
|---|---|---|
| Collapsible | open, close, toggle | opened, closed |
| Accordion | open, close, toggle | opened, closed |
| Toggle | press, unpress, toggle | pressed, unpressed |
| Switch | check, uncheck, toggle | checked, unchecked |
| ToggleGroup | select, deselect, toggle, set | selected, deselected |
| Progress | set | progress |
| Tabs | activate | tab-change |