{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "lazy-load", "type": "registry:ui", "title": "Lazy Load", "description": "A deferred-content container that fetches its own contents after the page paints (hx-trigger=\"load\") and swaps them in, with a reserved-space placeholder to prevent layout shift (CLS). Pairs with Skeleton for slow dashboard panels and per-tab content. Zero JS of its own — htmx owns the request and the IntersectionObserver.", "registryDependencies": [ "utils" ], "files": [ { "path": "registry/ui/lazy-load.tsx", "type": "registry:ui", "target": "components/ui/lazy-load.tsx", "content": "/** @jsxImportSource hono/jsx */\nimport type { PropsWithChildren } from \"hono/jsx\"\nimport { cn, type ClassValue } from \"@/registry/lib/cn\"\n\n// Lazy Load — shadcn-htmx, htmx v4 + Tailwind v4.\n//\n// A deferred-content container. It renders a placeholder immediately, then\n// fetches its own contents after the page paints and swaps them in. The\n// placeholder reserves vertical space so the swap does not push the page\n// around (Cumulative Layout Shift). Pair it with for slow\n// dashboard panels or per-tab content that you don't want to block first\n// paint on.\n//\n// shadcn/ui has no \"lazy load\" widget — it is a hypermedia loading pattern,\n// not a Radix primitive, so there is no React source of truth to mirror. We\n// build it straight from the htmx v4 lazy-load pattern and the platform docs:\n// repos/htmx/www/src/content/patterns/01-loading/03-lazy-load.md\n// (the canonical pattern: a placeholder div with hx-get + hx-trigger=\"load\";\n// htmx swaps the response in when it arrives. The \"Layout shift\" note\n// says to reserve space with min-height to protect the Lighthouse/CLS\n// score — that is exactly what `reserve`/min-height does here. The\n// \"Infinite loops\" note warns against echoing hx-trigger=\"load\" in the\n// response: our default hx-swap=\"innerHTML\" keeps the trigger host in\n// place, so the response body must NOT repeat the trigger.)\n// repos/htmx/www/src/content/reference/01-attributes/06-hx-trigger.md\n// (verified v4: synthetic `load` fires when the element enters the DOM —\n// \"Useful for lazy-loading content\"; `revealed` fires when it scrolls\n// into the viewport; use `intersect once` instead when the element lives\n// inside an `overflow-y: scroll` container.)\n// repos/htmx/www/src/content/reference/01-attributes/07-hx-swap.md\n// (verified v4: `innerHTML` — the default — replaces the *contents* of the\n// target, leaving our reserved-space wrapper in the DOM; `outerHTML`\n// replaces the wrapper wholesale, for when the response brings its own\n// box. We default to innerHTML so the reserved height survives the swap.)\n// repos/htmx/www/src/content/reference/01-attributes/01-hx-get.md\n// (the request the container issues for its own contents.)\n// repos/mdn/files/en-us/web/accessibility/aria/reference/attributes/aria-busy/index.md\n// (verified: aria-busy=\"true\" on a region tells AT \"this content is still\n// being modified — wait before announcing\". The role=\"status\" live region\n// announces once the busy content settles. Both ride away with the\n// innerHTML swap because they live on the wrapper, which is fine — htmx\n// flips nothing for us, so we keep them simple and static.)\n// repos/mdn/files/en-us/web/api/intersection_observer_api/index.md\n// (the platform API htmx's revealed/intersect triggers are built on —\n// \"implementing infinite-scrolling websites … as you scroll\".)\n//\n// Zero JS of our own: htmx owns the request and the IntersectionObserver; the\n// in-flight state is the placeholder we render. No emulation of any platform\n// feature — the trigger IS htmx's `load` event / the platform's\n// IntersectionObserver.\n\nexport type LazyLoadTrigger = \"load\" | \"revealed\" | \"intersect\"\nexport type LazyLoadSwap = \"innerHTML\" | \"outerHTML\"\n\n// Maps our trigger prop to the literal hx-trigger value. `intersect once`\n// fires a single time when the element first crosses the viewport (the\n// overflow-container form); `revealed` is the page-viewport form; `load`\n// fires immediately on insertion.\nconst TRIGGER_MAP: Record = {\n load: \"load\",\n revealed: \"revealed\",\n intersect: \"intersect once\",\n}\n\n// The reserved-space wrapper. min-h keeps a stable box so the swap doesn't\n// shift the page; centred so the default placeholder/spinner sits middle.\nconst rootClasses =\n \"flex w-full items-center justify-center text-sm text-muted-foreground\"\n\n// Default placeholder: a muted inline spinner + caption. It is the visible\n// \"loading\" state until the response swaps in. Pass children to override it\n// (e.g. a composed silhouette).\nfunction Spinner() {\n return (\n \n )\n}\n\ntype LazyLoadProps = PropsWithChildren<{\n // URL to fetch this container's contents from. Sets hx-get for you.\n src?: string\n // When the fetch fires. \"load\" → immediately on insertion (deferred but\n // eager); \"revealed\" → when scrolled into the page viewport; \"intersect\"\n // → first viewport crossing inside an overflow-y:scroll container.\n trigger?: LazyLoadTrigger\n // How the response lands. \"innerHTML\" (default) replaces the contents and\n // keeps this reserved-space wrapper; \"outerHTML\" replaces the wrapper.\n swap?: LazyLoadSwap\n // Reserved minimum height (any CSS length, e.g. \"12rem\" or \"200px\"). Sets\n // min-height inline so the box holds its size before content arrives —\n // prevents layout shift (CLS).\n reserve?: string\n // Accessible name for the loading region (\"Loading sales report\").\n ariaLabel?: string\n class?: ClassValue\n id?: string\n // htmx / data / aria attributes ride onto the container. Forwarded so call\n // sites can override hx-target, add hx-indicator, hx-vals, hx-swap timing,\n // etc.\n [key: `hx-${string}`]: any\n [key: `data-${string}`]: any\n [key: `aria-${string}`]: any\n}>\n\nexport function LazyLoad(props: LazyLoadProps) {\n const {\n src,\n trigger = \"load\",\n swap = \"innerHTML\",\n reserve,\n ariaLabel = \"Loading\",\n class: className,\n id,\n children,\n ...rest\n } = props as any\n\n return (\n \n {children ?? (\n \n \n Loading…\n \n )}\n \n )\n}\n" }, { "path": "registry/jinja2/lazy-load.html", "type": "registry:file", "target": "templates/components/lazy-load.html", "content": "{# Lazy Load macro — shadcn-htmx, htmx v4 + Tailwind v4.\n Mirrors registry/ui/lazy-load.tsx.\n\n A deferred-content container. It renders a placeholder immediately, then\n fetches its own contents after the page paints (hx-get + hx-trigger=\"load\")\n and swaps them in. `reserve` sets min-height so the swap does not shift the\n page (CLS). trigger=\"load\" fires on insertion; \"revealed\" fires on scroll\n into the page viewport; \"intersect\" fires once inside an overflow-y:scroll\n container. swap=\"innerHTML\" (default) keeps this wrapper; \"outerHTML\"\n replaces it. Default hx-swap=\"innerHTML\" keeps the trigger host, so the\n server response must NOT repeat hx-trigger=\"load\" (avoids an infinite loop).\n\n Sources cited in lazy-load.tsx:\n repos/htmx/.../patterns/01-loading/03-lazy-load.md\n repos/htmx/.../reference/01-attributes/{01-hx-get,06-hx-trigger,07-hx-swap}.md\n repos/mdn/.../web/accessibility/aria/reference/attributes/aria-busy/index.md\n repos/mdn/.../web/api/intersection_observer_api/index.md\n\n Usage:\n {% from \"components/lazy-load.html\" import lazy_load %}\n\n {{ lazy_load(src=\"/dashboard/sales\", reserve=\"12rem\", aria_label=\"Loading sales\") }}\n {{ lazy_load(src=\"/comments\", trigger=\"revealed\", reserve=\"8rem\") }} #}\n\n{% macro lazy_load(src=none, trigger=\"load\", swap=\"innerHTML\", reserve=none, aria_label=\"Loading\", id=none, extra_class=\"\", **attrs) %}\n{% if caller %}{{ caller() }}{% else %}Loading…{% endif %}\n{% endmacro %}\n" }, { "path": "registry/go-templates/lazy-load.tmpl", "type": "registry:file", "target": "components/lazy-load.tmpl", "content": "{{/* Lazy Load template — shadcn-htmx, htmx v4 + Tailwind v4.\n Mirrors registry/ui/lazy-load.tsx.\n\n A deferred-content container. It renders a placeholder immediately, then\n fetches its own contents after the page paints (hx-get + hx-trigger=\"load\")\n and swaps them in. Reserve sets min-height so the swap does not shift the\n page (CLS). Trigger \"load\" fires on insertion; \"revealed\" fires on scroll\n into the page viewport; \"intersect\" fires once inside an overflow-y:scroll\n container. Swap \"innerHTML\" (default) keeps this wrapper; \"outerHTML\"\n replaces it. The default hx-swap=\"innerHTML\" keeps the trigger host, so\n the server response must NOT repeat hx-trigger=\"load\" (infinite loop).\n\n Sources cited in lazy-load.tsx:\n repos/htmx/.../patterns/01-loading/03-lazy-load.md\n repos/htmx/.../reference/01-attributes/{01-hx-get,06-hx-trigger,07-hx-swap}.md\n repos/mdn/.../web/accessibility/aria/reference/attributes/aria-busy/index.md\n repos/mdn/.../web/api/intersection_observer_api/index.md\n\n Usage:\n {{template \"lazy_load\" (dict \"Src\" \"/dashboard/sales\" \"Reserve\" \"12rem\" \"AriaLabel\" \"Loading sales\")}}\n {{template \"lazy_load\" (dict \"Src\" \"/comments\" \"Trigger\" \"revealed\" \"Reserve\" \"8rem\")}} */}}\n\n{{define \"lazy_load\"}}\n{{- $trigger := or .Trigger \"load\" -}}\n{{- $swap := or .Swap \"innerHTML\" -}}\n
{{if .Body}}{{htmlSafe .Body}}{{else}}Loading…{{end}}
\n{{end}}\n" }, { "path": "registry/phoenix/lazy_load.ex", "type": "registry:file", "target": "lib/my_app_web/components/lazy_load.ex", "content": "defmodule ShadcnHtmx.Components.LazyLoad do\n @moduledoc \"\"\"\n Lazy Load — shadcn-htmx, htmx v4 + Tailwind v4 for Phoenix.\n\n A deferred-content container. It renders a placeholder immediately, then\n fetches its own contents after the page paints (`hx-get` + `hx-trigger=\"load\"`)\n and swaps them in. `reserve` sets `min-height` so the swap does not shift the\n page (Cumulative Layout Shift). Pair it with `<.skeleton>` for slow dashboard\n panels or per-tab content.\n\n * `trigger=\"load\"` — fires immediately when the element enters the DOM.\n * `trigger=\"revealed\"` — fires when it scrolls into the page viewport.\n * `trigger=\"intersect\"` — fires once inside an `overflow-y: scroll`\n container (`intersect once`).\n * `swap=\"innerHTML\"` (default) keeps this reserved-space wrapper; the server\n response must NOT repeat `hx-trigger=\"load\"` or it loops. `swap=\"outerHTML\"`\n replaces the wrapper wholesale.\n\n Sources (read, not copied) — see registry/ui/lazy-load.tsx:\n repos/htmx/.../patterns/01-loading/03-lazy-load.md\n repos/htmx/.../reference/01-attributes/{01-hx-get,06-hx-trigger,07-hx-swap}.md\n repos/mdn/.../web/accessibility/aria/reference/attributes/aria-busy/index.md\n repos/mdn/.../web/api/intersection_observer_api/index.md\n\n ## Examples\n\n <.lazy_load src={~p\"/dashboard/sales\"} reserve=\"12rem\" aria-label=\"Loading sales\" />\n\n <.lazy_load src={~p\"/comments\"} trigger=\"revealed\" reserve=\"8rem\" />\n \"\"\"\n\n use Phoenix.Component\n\n attr :src, :string, default: nil\n attr :trigger, :string, default: \"load\", values: ~w(load revealed intersect)\n attr :swap, :string, default: \"innerHTML\", values: ~w(innerHTML outerHTML)\n attr :reserve, :string, default: nil\n attr :\"aria-label\", :string, default: \"Loading\"\n attr :class, :string, default: nil\n attr :rest, :global\n slot :inner_block\n\n def lazy_load(assigns) do\n ~H\"\"\"\n \"intersect once\"\n \"revealed\" -> \"revealed\"\n _ -> \"load\"\n end\n }\n hx-swap={@swap}\n style={@reserve && \"min-height:#{@reserve}\"}\n class={[\"flex w-full items-center justify-center text-sm text-muted-foreground\", @class]}\n {@rest}\n >\n <%= if @inner_block != [] do %>\n {render_slot(@inner_block)}\n <% else %>\n \n \n Loading…\n \n <% end %>\n \n \"\"\"\n end\nend\n" }, { "path": "registry/html/lazy-load.html", "type": "registry:file", "target": "snippets/lazy-load.html", "content": "\n\n\n
\n \n \n Loading…\n \n
\n" } ] }