Corex.
View Source
Phoenix implementation of Zag.js Avatar.
Anatomy
Fallback
<.avatar src="" class="avatar">
<:fallback>
<span class="font-semibold">AB</span>
</:fallback>
</.avatar>Value slot
Override fallback body and receive the current src as value. When :value is omitted, <:fallback> is used.
<.avatar src="https://corex-ui.com/images/avatar.png" alt="" class="avatar">
<:value :let={src}>
{if src, do: "IMG", else: " - "}
</:value>
</.avatar>Pending
With pending={true}, the hook and <img> are not mounted until pending={false}. Use :loading or avatar_skeleton/1.
<.avatar pending class="avatar">
<:loading><span class="text-sm">Loading</span></:loading>
</.avatar>API
Requires a stable id on <.avatar>.
| Function | Action | Returns |
|---|---|---|
set_src/2 | Set image URL (client) | %Phoenix.LiveView.JS{} |
set_src/3 | Set image URL (server) | socket |
loaded/1 | Read loaded state (client) | %Phoenix.LiveView.JS{} |
loaded/2 | Read loaded state with respond_to (client) | %Phoenix.LiveView.JS{} |
loaded/3 | Read loaded state (server) | socket |
For loaded, use respond_to: :server | :client | :both. LiveView receives avatar_loaded_response; the DOM receives avatar-loaded.
Events
Pick an event name and pass it to on_* on <.avatar>.
Server events
| Event | When | Payload |
|---|---|---|
on_status_change="avatar_status_changed" | Image load status changes | %{"id" => id, "status" => "loaded" | "error"} |
on_status_change
<.avatar
class="avatar"
src="https://corex-ui.com/images/avatar.png"
alt="Avatar"
on_status_change="avatar_status_changed"
>
<:fallback>JD</:fallback>
</.avatar>def handle_event("avatar_status_changed", %{"id" => _id, "status" => status}, socket) do
{:noreply, assign(socket, :avatar_status, status)}
endClient events
| Event | When | event.detail |
|---|---|---|
on_status_change_client="avatar-status-changed" | Image load status changes | id, status |
on_status_change_client
<.avatar
id="avatar-events-client"
class="avatar"
src="https://corex-ui.com/images/avatar.png"
on_status_change_client="avatar-status-changed"
>
<:fallback>JD</:fallback>
</.avatar>const el = document.getElementById("avatar-events-client");
el?.addEventListener("avatar-status-changed", (e) => console.log(e.detail));Style
Target parts with data-scope and data-part, or use Corex Design: import tokens and avatar.css, then set class="avatar" on <.avatar>.
[data-scope="avatar"][data-part="root"] {}
[data-scope="avatar"][data-part="image"] {}
[data-scope="avatar"][data-part="fallback"] {}
[data-scope="avatar"][data-part="skeleton"] {}@import "../corex/main.css";
@import "../corex/tokens/themes/neo/light.css";
@import "../corex/components/avatar.css";Stack modifiers on the host (class on <.avatar>).
Color
| Modifier | Classes |
|---|---|
| Default | avatar |
| Accent | avatar avatar--accent |
| Brand | avatar avatar--brand |
| Alert | avatar avatar--alert |
| Info | avatar avatar--info |
| Success | avatar avatar--success |
Size
| Modifier | Classes |
|---|---|
| SM | avatar avatar--sm |
| MD | avatar avatar--md |
| LG | avatar avatar--lg |
| XL | avatar avatar--xl |
Summary
Components
Static loading placeholder for use with <.async_result> or when pending is true without a :loading slot.
Components
Attributes
id(:string) - The id of the avatar.src(:string) - Image source URL. Defaults tonil.alt(:string) - Alternative text for the image. Defaults to"".dir(:string) - Direction. Defaults tonil. Must be one ofnil,"ltr", or"rtl".pending(:boolean) - When true, renders only the loading UI (:loadingslot oravatar_skeleton/1), without the Avatar hook. Defaults tofalse.on_status_change(:string) - Server event when image load status changes. Defaults tonil.on_status_change_client(:string) - Client event when image load status changes. Defaults tonil.- Global attributes are accepted.
Slots
loading- Custom loading content whenpendingis true. Overrides defaultavatar_skeleton/1. Accepts attributes:class(:string)
fallback- Content for the fallback part when the image is absent or not yet shown. Accepts attributes:class(:string)
value- Optional replacement for:fallbackinner content. Use:let={value}-valueis the imagesrc(ornil). Accepts attributes:class(:string)
Static loading placeholder for use with <.async_result> or when pending is true without a :loading slot.
Attributes
- Global attributes are accepted.
API
Read image load status from phx-click. Optional respond_to: :server (default), :client, or :both.
<.action phx-click={Corex.Avatar.loaded("my-avatar", respond_to: :both)}>Status</.action>
<.avatar id="my-avatar" class="avatar" src="https://example.com/a.png" />document.getElementById("my-avatar")?.dispatchEvent(
new CustomEvent("corex:avatar:loaded", {
bubbles: false,
detail: { respond_to: "both" },
})
);Read load status from handle_event. Same respond_to behavior as loaded/2.
<.action phx-click="avatar_status">Status</.action>
<.avatar id="my-avatar" class="avatar" src="https://example.com/a.png" />def handle_event("avatar_status", _, socket) do
{:noreply, Corex.Avatar.loaded(socket, "my-avatar", respond_to: :server)}
endSet the image src from a control (phx-click).
<.action phx-click={Corex.Avatar.set_src("my-avatar", "https://example.com/a.png")}>A</.action>
<.avatar id="my-avatar" class="avatar" src={nil} />document.getElementById("my-avatar")?.dispatchEvent(
new CustomEvent("corex:avatar:set-src", {
bubbles: false,
detail: { src: "https://example.com/a.png" },
})
);Set src from handle_event.
<.action phx-click="avatar_a" phx-value-src="https://example.com/a.png">A</.action>
<.avatar id="my-avatar" class="avatar" src={nil} />def handle_event("avatar_a", %{"src" => src}, socket) do
{:noreply, Corex.Avatar.set_src(socket, "my-avatar", src)}
end