@farcaster/snap 2.0.2 → 2.0.3

package/dist/react/index.d.ts

@@ -42,7 +42,7 @@ export type SnapActionHandlers = {
         buyToken?: string;
     }) => void;
 };
-export declare function SnapCard({ snap, handlers, loading, appearance, maxWidth, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, }: {
+export declare function SnapCard({ snap, handlers, loading, appearance, maxWidth, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -56,4 +56,6 @@ export declare function SnapCard({ snap, handlers, loading, appearance, maxWidth
     actionError?: string | null;
     /** When true, renders without card frame (no border, background, or padding). */
     plain?: boolean;
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/react/index.js

@@ -4,9 +4,9 @@ import { SPEC_VERSION_2 } from "../constants.js";
 import { SnapCardV1 } from "./v1/snap-view.js";
 import { SnapCardV2 } from "./v2/snap-view.js";
 // ─── SnapCard ────────────────────────────────────────
-export function SnapCard({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, }) {
+export function SnapCard({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, }) {
     if (snap.version === SPEC_VERSION_2) {
-        return (_jsx(SnapCardV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, maxWidth: maxWidth, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, plain: plain }));
+        return (_jsx(SnapCardV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, maxWidth: maxWidth, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay }));
     }
-    return (_jsx(SnapCardV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, maxWidth: maxWidth, actionError: actionError, plain: plain }));
+    return (_jsx(SnapCardV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, maxWidth: maxWidth, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay }));
 }

package/dist/react/snap-view-core.d.ts

@@ -1,11 +1,22 @@
+import { type ReactNode } from "react";
 import type { SnapActionHandlers, SnapPage } from "./index.js";
 export declare function applyStatePaths(model: Record<string, unknown>, changes: {
     path: string;
     value: unknown;
 }[] | Record<string, unknown>): void;
-export declare function SnapViewCore({ snap, handlers, loading, appearance, }: {
+export declare function SnapLoadingOverlay({ appearance, accentHex, active, }: {
+    appearance: "light" | "dark";
+    accentHex: string;
+    active: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function SnapViewCore({ snap, handlers, loading, appearance, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
     appearance?: "light" | "dark";
+    /**
+     * Custom content rendered while `loading` is true. When `undefined` (default)
+     * the built-in spinner + backdrop is used. Pass `null` to render nothing.
+     */
+    loadingOverlay?: ReactNode;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/react/snap-view-core.js

@@ -1,5 +1,5 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { snapJsonRenderCatalog } from "../ui/index.js";
 import { SnapCatalogView } from "./catalog-renderer.js";
 import { SnapPreviewAccentProvider } from "./accent-context.js";
@@ -75,7 +75,7 @@ function ConfettiOverlay() {
                     animation: `confettiFall ${duration}s ease-in ${delay}s forwards`,
                 } }, id))), _jsx("style", { children: `@keyframes confettiFall{0%{top:-20px;opacity:1;transform:rotate(0deg) translateX(0)}50%{opacity:1}100%{top:110%;opacity:0;transform:rotate(720deg) translateX(${Math.random() > 0.5 ? "" : "-"}40px)}}` })] }));
 }
-function SnapLoadingOverlay({ appearance, accentHex, active, }) {
+export function SnapLoadingOverlay({ appearance, accentHex, active, }) {
     const isDark = appearance === "dark";
     const tint = isDark ? "rgba(0, 0, 0, 0.1)" : "rgba(255, 255, 255, 0.2)";
     const trackColor = isDark
@@ -130,7 +130,7 @@ const PALETTE = [
 ];
 // ─── SnapViewCore ────────────────────────────────────
 // Shared rendering logic used by both v1 and v2.
-export function SnapViewCore({ snap, handlers, loading = false, appearance = "dark", }) {
+export function SnapViewCore({ snap, handlers, loading = false, appearance = "dark", loadingOverlay, }) {
     const spec = snap.ui;
     const initialState = useMemo(() => spec.state ?? { inputs: {} }, [spec]);
     const stateRef = useRef(initialState);
@@ -221,7 +221,7 @@ export function SnapViewCore({ snap, handlers, loading = false, appearance = "da
                 break;
         }
     }, [handlers]);
-    return (_jsxs("div", { style: { position: "relative", width: "100%" }, children: [showConfetti && _jsx(ConfettiOverlay, {}), _jsx(SnapLoadingOverlay, { appearance: appearance, accentHex: accentHex, active: loading }), _jsx("div", { style: previewSurfaceStyle, children: _jsx(SnapPreviewAccentProvider, { pageAccent: snap.theme?.accent, appearance: appearance, children: _jsx(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
+    return (_jsxs("div", { style: { position: "relative", width: "100%" }, children: [showConfetti && _jsx(ConfettiOverlay, {}), loadingOverlay === undefined ? (_jsx(SnapLoadingOverlay, { appearance: appearance, accentHex: accentHex, active: loading })) : loading ? (_jsx(_Fragment, { children: loadingOverlay })) : null, _jsx("div", { style: previewSurfaceStyle, children: _jsx(SnapPreviewAccentProvider, { pageAccent: snap.theme?.accent, appearance: appearance, children: _jsx(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
                             applyStatePaths(stateRef.current, changes);
                         }, onAction: handleAction }, pageKey) }) })] }));
 }

package/dist/react/v1/snap-view.d.ts

@@ -1,11 +1,14 @@
+import { type ReactNode } from "react";
 import type { SnapPage, SnapActionHandlers } from "../index.js";
-export declare function SnapViewV1({ snap, handlers, loading, appearance, }: {
+export declare function SnapViewV1({ snap, handlers, loading, appearance, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
     appearance?: "light" | "dark";
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react/jsx-runtime").JSX.Element;
-export declare function SnapCardV1({ snap, handlers, loading, appearance, maxWidth, actionError, plain, }: {
+export declare function SnapCardV1({ snap, handlers, loading, appearance, maxWidth, actionError, plain, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -13,4 +16,6 @@ export declare function SnapCardV1({ snap, handlers, loading, appearance, maxWid
     maxWidth?: number;
     actionError?: string | null;
     plain?: boolean;
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/react/v1/snap-view.js

@@ -1,12 +1,13 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from "react";
-import { SnapViewCore } from "../snap-view-core.js";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { SnapViewCore, SnapLoadingOverlay } from "../snap-view-core.js";
+import { resolveSnapPaletteHex } from "../lib/resolve-palette-hex.js";
 const SNAP_MAX_HEIGHT = 500;
-export function SnapViewV1({ snap, handlers, loading = false, appearance = "dark", }) {
-    return (_jsx(SnapViewCore, { snap: snap, handlers: handlers, loading: loading, appearance: appearance }));
+export function SnapViewV1({ snap, handlers, loading = false, appearance = "dark", loadingOverlay, }) {
+    return (_jsx(SnapViewCore, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, loadingOverlay: loadingOverlay }));
 }
-export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, actionError, plain = false, }) {
+export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, actionError, plain = false, loadingOverlay, }) {
     const isDark = appearance === "dark";
     const borderColor = isDark ? "rgba(255,255,255,0.1)" : "rgba(0,0,0,0.1)";
     const surfaceBg = isDark ? "rgba(255,255,255,0.05)" : "rgba(0,0,0,0.02)";
@@ -43,6 +44,7 @@ export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark
         }
     }, [isExpandable]);
     const isClipped = isExpandable && !isExpanded;
+    const accentHex = useMemo(() => resolveSnapPaletteHex(snap.theme?.accent ?? "purple", appearance), [snap.theme?.accent, appearance]);
     return (_jsxs("div", { style: {
             position: "relative",
             width: "100%",
@@ -58,7 +60,7 @@ export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark
                         maxHeight: SNAP_MAX_HEIGHT,
                         overflow: "hidden",
                     }
-                    : undefined, children: _jsx("div", { ref: contentRef, style: plain ? undefined : { padding: 16 }, children: _jsx(SnapViewV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance }) }) }), isExpandable ? (_jsx("div", { style: {
+                    : undefined, children: _jsx("div", { ref: contentRef, style: plain ? undefined : { padding: 16 }, children: _jsx(SnapViewV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, loadingOverlay: null }) }) }), loadingOverlay === undefined ? (_jsx(SnapLoadingOverlay, { appearance: appearance, accentHex: accentHex, active: loading })) : loading ? (_jsx(_Fragment, { children: loadingOverlay })) : null, isExpandable ? (_jsx("div", { style: {
                     display: "flex",
                     justifyContent: "center",
                     padding: plain ? "8px 0 0" : "10px 16px 12px",

package/dist/react/v2/snap-view.d.ts

@@ -1,15 +1,17 @@
 import { type ReactNode } from "react";
 import type { ValidationResult } from "../../validator.js";
 import type { SnapPage, SnapActionHandlers } from "../index.js";
-export declare function SnapViewV2({ snap, handlers, loading, appearance, onValidationError, validationErrorFallback, }: {
+export declare function SnapViewV2({ snap, handlers, loading, appearance, onValidationError, validationErrorFallback, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
     appearance?: "light" | "dark";
     onValidationError?: (result: ValidationResult) => void;
     validationErrorFallback?: ReactNode;
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react/jsx-runtime").JSX.Element | null;
-export declare function SnapCardV2({ snap, handlers, loading, appearance, maxWidth, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, }: {
+export declare function SnapCardV2({ snap, handlers, loading, appearance, maxWidth, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -20,4 +22,6 @@ export declare function SnapCardV2({ snap, handlers, loading, appearance, maxWid
     validationErrorFallback?: ReactNode;
     actionError?: string | null;
     plain?: boolean;
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/react/v2/snap-view.js

@@ -2,7 +2,8 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useMemo } from "react";
 import { validateSnapResponse } from "../../validator.js";
-import { SnapViewCore } from "../snap-view-core.js";
+import { SnapViewCore, SnapLoadingOverlay } from "../snap-view-core.js";
+import { resolveSnapPaletteHex } from "../lib/resolve-palette-hex.js";
 const SNAP_MAX_HEIGHT = 500;
 const SNAP_WARNING_HEIGHT = 700;
 // ─── Default validation error fallback ────────────────
@@ -19,7 +20,7 @@ function SnapValidationFallback({ appearance, message, }) {
         }, children: _jsx("span", { children: message ? `Unable to render snap: ${message}` : "Unable to render snap" }) }));
 }
 // ─── SnapViewV2 ──────────────────────────────────────
-export function SnapViewV2({ snap, handlers, loading = false, appearance = "dark", onValidationError, validationErrorFallback, }) {
+export function SnapViewV2({ snap, handlers, loading = false, appearance = "dark", onValidationError, validationErrorFallback, loadingOverlay, }) {
     const validation = useMemo(() => validateSnapResponse(snap), [snap]);
     const valid = validation.valid;
     const validationMessage = validation.issues[0]?.message;
@@ -39,15 +40,16 @@ export function SnapViewV2({ snap, handlers, loading = false, appearance = "dark
             return null;
         return _jsx(_Fragment, { children: validationErrorFallback ?? _jsx(SnapValidationFallback, { appearance: appearance, message: validationMessage }) });
     }
-    return (_jsx(SnapViewCore, { snap: snap, handlers: handlers, loading: loading, appearance: appearance }));
+    return (_jsx(SnapViewCore, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, loadingOverlay: loadingOverlay }));
 }
 // ─── SnapCardV2 ──────────────────────────────────────
-export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, }) {
+export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, }) {
     const maxHeight = showOverflowWarning ? SNAP_WARNING_HEIGHT : SNAP_MAX_HEIGHT;
     const isDark = appearance === "dark";
     const bg = isDark ? "rgba(0,0,0,0.85)" : "rgba(255,255,255,0.9)";
     const borderColor = isDark ? "rgba(255,255,255,0.1)" : "rgba(0,0,0,0.1)";
     const surfaceBg = isDark ? "rgba(255,255,255,0.05)" : "rgba(0,0,0,0.02)";
+    const accentHex = useMemo(() => resolveSnapPaletteHex(snap.theme?.accent ?? "purple", appearance), [snap.theme?.accent, appearance]);
     return (_jsxs(_Fragment, { children: [_jsxs("div", { style: {
                     position: "relative",
                     width: "100%",
@@ -59,7 +61,7 @@ export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark
                         border: `1px solid ${borderColor}`,
                         backgroundColor: surfaceBg,
                     }),
-                }, children: [_jsx("div", { style: plain ? undefined : { padding: 16 }, children: _jsx(SnapViewV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback }) }), showOverflowWarning && (_jsxs("div", { style: {
+                }, children: [_jsx("div", { style: plain ? undefined : { padding: 16 }, children: _jsx(SnapViewV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, loadingOverlay: null }) }), loadingOverlay === undefined ? (_jsx(SnapLoadingOverlay, { appearance: appearance, accentHex: accentHex, active: loading })) : loading ? (_jsx(_Fragment, { children: loadingOverlay })) : null, showOverflowWarning && (_jsxs("div", { style: {
                             position: "absolute",
                             top: SNAP_MAX_HEIGHT,
                             left: 0,

package/dist/react-native/index.d.ts

@@ -7,7 +7,7 @@ import { hexToRgba } from "./use-snap-palette.js";
 export type { JsonValue, SnapPage, SnapActionHandlers } from "./types.js";
 export { useSnapTheme, hexToRgba };
 export type { SnapNativeColors };
-export declare function SnapCard({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, }: {
+export declare function SnapCard({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -25,4 +25,6 @@ export declare function SnapCard({ snap, handlers, loading, appearance, colors,
     actionError?: string | null;
     /** When true, renders without card frame (no border, background, or padding). */
     plain?: boolean;
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react").JSX.Element;

package/dist/react-native/index.js

@@ -7,9 +7,9 @@ import { SnapCardV2 } from "./v2/snap-view.js";
 // ─── Re-exports ───────────────────────────────────────
 export { useSnapTheme, hexToRgba };
 // ─── SnapCard (version-switching) ─────────────────────
-export function SnapCard({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, }) {
+export function SnapCard({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, }) {
     if (snap.version === SPEC_VERSION_2) {
-        return (_jsx(SnapCardV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, plain: plain }));
+        return (_jsx(SnapCardV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay }));
     }
-    return (_jsx(SnapCardV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius, actionError: actionError, plain: plain }));
+    return (_jsx(SnapCardV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay }));
 }

package/dist/react-native/snap-view-core.d.ts

@@ -1,11 +1,21 @@
+import { type ReactNode } from "react";
 import type { SnapPage, SnapActionHandlers } from "./types.js";
 export declare function applyStatePaths(model: Record<string, unknown>, changes: {
     path: string;
     value: unknown;
 }[] | Record<string, unknown>): void;
 export declare function resolveAccentHex(accent: string | undefined, appearance: "light" | "dark"): string;
-export declare function SnapViewCoreInner({ snap, handlers, loading, }: {
+export declare function SnapViewCoreInner({ snap, handlers, loading, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
+    /**
+     * Custom content rendered while `loading` is true. When `undefined` (default)
+     * the built-in ActivityIndicator overlay is used. Pass `null` to render nothing.
+     */
+    loadingOverlay?: ReactNode;
+}): import("react").JSX.Element;
+export declare function SnapLoadingOverlay({ appearance, accentHex, }: {
+    appearance: "light" | "dark";
+    accentHex: string;
 }): import("react").JSX.Element;

package/dist/react-native/snap-view-core.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { snapJsonRenderCatalog } from "@farcaster/snap/ui";
 import { SnapCatalogView } from "./catalog-renderer.js";
 import { useSnapTheme } from "./theme.js";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
 import { ActivityIndicator, StyleSheet, View } from "react-native";
 import { DEFAULT_THEME_ACCENT, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, } from "@farcaster/snap";
 // ─── Shared helpers ──────────────────────────────────
@@ -45,7 +45,7 @@ export function resolveAccentHex(accent, appearance) {
     return map[name];
 }
 // ─── Core rendering component (no validation) ────────
-export function SnapViewCoreInner({ snap, handlers, loading = false, }) {
+export function SnapViewCoreInner({ snap, handlers, loading = false, loadingOverlay, }) {
     const { mode } = useSnapTheme();
     const spec = snap.ui;
     const accentHex = resolveAccentHex(snap.theme?.accent, mode);
@@ -134,15 +134,24 @@ export function SnapViewCoreInner({ snap, handlers, loading = false, }) {
                 break;
         }
     }, []);
-    return (_jsxs(View, { style: styles.container, children: [loading ? (_jsx(View, { style: [
-                    styles.overlay,
-                    {
-                        backgroundColor: mode === "dark" ? "rgba(0,0,0,0.1)" : "rgba(255,255,255,0.2)",
-                    },
-                ], children: _jsx(ActivityIndicator, { size: "large", color: accentHex }) })) : null, _jsx(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
+    return (_jsxs(View, { style: styles.container, children: [loading
+                ? loadingOverlay === undefined
+                    ? (_jsx(SnapLoadingOverlay, { appearance: mode, accentHex: accentHex }))
+                    : loadingOverlay
+                : null, _jsx(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
                     applyStatePaths(stateRef.current, changes);
                 }, onAction: handleAction }, pageKey)] }));
 }
+export function SnapLoadingOverlay({ appearance, accentHex, }) {
+    return (_jsx(View, { style: [
+            styles.overlay,
+            {
+                backgroundColor: appearance === "dark"
+                    ? "rgba(0,0,0,0.1)"
+                    : "rgba(255,255,255,0.2)",
+            },
+        ], children: _jsx(ActivityIndicator, { size: "large", color: accentHex }) }));
+}
 const styles = StyleSheet.create({
     container: {
         width: "100%",

package/dist/react-native/v1/snap-view.d.ts

@@ -1,18 +1,22 @@
+import { type ReactNode } from "react";
 import { type SnapNativeColors } from "../theme.js";
 import type { SnapPage, SnapActionHandlers } from "../types.js";
-export declare function SnapViewV1Inner({ snap, handlers, loading, }: {
+export declare function SnapViewV1Inner({ snap, handlers, loading, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
+    loadingOverlay?: ReactNode;
 }): import("react").JSX.Element;
-export declare function SnapViewV1({ snap, handlers, loading, appearance, colors, }: {
+export declare function SnapViewV1({ snap, handlers, loading, appearance, colors, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
     appearance?: "light" | "dark";
     colors?: Partial<SnapNativeColors>;
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react").JSX.Element;
-export declare function SnapCardV1({ snap, handlers, loading, appearance, colors, borderRadius, actionError, plain, }: {
+export declare function SnapCardV1({ snap, handlers, loading, appearance, colors, borderRadius, actionError, plain, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -21,4 +25,6 @@ export declare function SnapCardV1({ snap, handlers, loading, appearance, colors
     borderRadius?: number;
     actionError?: string | null;
     plain?: boolean;
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react").JSX.Element;

package/dist/react-native/v1/snap-view.js

@@ -2,18 +2,19 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { useEffect, useState } from "react";
 import { View, Text, StyleSheet, Pressable } from "react-native";
 import { SnapThemeProvider, useSnapTheme } from "../theme.js";
-import { SnapViewCoreInner } from "../snap-view-core.js";
+import { SnapLoadingOverlay, SnapViewCoreInner, resolveAccentHex, } from "../snap-view-core.js";
 const SNAP_MAX_HEIGHT = 500;
 // ─── SnapViewV1 (no validation) ──────────────────────
-export function SnapViewV1Inner({ snap, handlers, loading = false, }) {
-    return (_jsx(SnapViewCoreInner, { snap: snap, handlers: handlers, loading: loading }));
+export function SnapViewV1Inner({ snap, handlers, loading = false, loadingOverlay, }) {
+    return (_jsx(SnapViewCoreInner, { snap: snap, handlers: handlers, loading: loading, loadingOverlay: loadingOverlay }));
 }
-export function SnapViewV1({ snap, handlers, loading = false, appearance = "dark", colors, }) {
-    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapViewV1Inner, { snap: snap, handlers: handlers, loading: loading }) }));
+export function SnapViewV1({ snap, handlers, loading = false, appearance = "dark", colors, loadingOverlay, }) {
+    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapViewV1Inner, { snap: snap, handlers: handlers, loading: loading, loadingOverlay: loadingOverlay }) }));
 }
 // ─── SnapCardV1 (card frame with expandable clipping) ──
-function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, actionError, appearance, plain, }) {
-    const { colors } = useSnapTheme();
+function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, actionError, appearance, plain, loadingOverlay, }) {
+    const { colors, mode } = useSnapTheme();
+    const accentHex = resolveAccentHex(snap.theme?.accent, mode);
     const [contentHeight, setContentHeight] = useState(0);
     const [isExpanded, setIsExpanded] = useState(false);
     useEffect(() => {
@@ -36,7 +37,11 @@ function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, action
                                         : currentHeight === nextHeight
                                             ? currentHeight
                                             : nextHeight);
-                                }, style: plain ? undefined : cardStyles.body, children: _jsx(SnapViewV1Inner, { snap: snap, handlers: handlers, loading: loading }) }) }), isExpandable ? (_jsx(View, { style: [
+                                }, style: plain ? undefined : cardStyles.body, children: _jsx(SnapViewV1Inner, { snap: snap, handlers: handlers, loading: loading, loadingOverlay: null }) }) }), loading
+                            ? loadingOverlay === undefined
+                                ? _jsx(SnapLoadingOverlay, { appearance: mode, accentHex: accentHex })
+                                : loadingOverlay
+                            : null, isExpandable ? (_jsx(View, { style: [
                                 cardStyles.expandRow,
                                 plain
                                     ? cardStyles.expandRowPlain
@@ -59,8 +64,8 @@ function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, action
                     },
                 ], children: actionError }))] }));
 }
-export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, actionError, plain = false, }) {
-    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV1Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius, actionError: actionError, appearance: appearance, plain: plain }) }));
+export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, actionError, plain = false, loadingOverlay, }) {
+    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV1Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius, actionError: actionError, appearance: appearance, plain: plain, loadingOverlay: loadingOverlay }) }));
 }
 const cardStyles = StyleSheet.create({
     frameRing: { alignSelf: "stretch" },

package/dist/react-native/v2/snap-view.d.ts

@@ -2,14 +2,15 @@ import type { ReactNode } from "react";
 import { type SnapNativeColors } from "../theme.js";
 import { type ValidationResult } from "@farcaster/snap";
 import type { SnapPage, SnapActionHandlers } from "../types.js";
-export declare function SnapViewV2Inner({ snap, handlers, loading, onValidationError, validationErrorFallback, }: {
+export declare function SnapViewV2Inner({ snap, handlers, loading, onValidationError, validationErrorFallback, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
     onValidationError?: (result: ValidationResult) => void;
     validationErrorFallback?: ReactNode;
+    loadingOverlay?: ReactNode;
 }): import("react").JSX.Element;
-export declare function SnapViewV2({ snap, handlers, loading, appearance, colors, onValidationError, validationErrorFallback, }: {
+export declare function SnapViewV2({ snap, handlers, loading, appearance, colors, onValidationError, validationErrorFallback, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -17,8 +18,10 @@ export declare function SnapViewV2({ snap, handlers, loading, appearance, colors
     colors?: Partial<SnapNativeColors>;
     onValidationError?: (result: ValidationResult) => void;
     validationErrorFallback?: ReactNode;
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react").JSX.Element;
-export declare function SnapCardV2({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, }: {
+export declare function SnapCardV2({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -30,4 +33,6 @@ export declare function SnapCardV2({ snap, handlers, loading, appearance, colors
     validationErrorFallback?: ReactNode;
     actionError?: string | null;
     plain?: boolean;
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react").JSX.Element;

package/dist/react-native/v2/snap-view.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { useEffect, useMemo, useState } from "react";
 import { Platform, StyleSheet, Text, View } from "react-native";
 import { SnapThemeProvider, useSnapTheme } from "../theme.js";
-import { SnapViewCoreInner } from "../snap-view-core.js";
+import { SnapLoadingOverlay, SnapViewCoreInner, resolveAccentHex, } from "../snap-view-core.js";
 import { validateSnapResponse, } from "@farcaster/snap";
 // ─── Constants ───────────────────────────────────────
 const SNAP_MAX_HEIGHT = 500;
@@ -24,7 +24,7 @@ const fallbackStyles = StyleSheet.create({
     },
 });
 // ─── SnapViewV2 (with validation) ────────────────────
-export function SnapViewV2Inner({ snap, handlers, loading = false, onValidationError, validationErrorFallback, }) {
+export function SnapViewV2Inner({ snap, handlers, loading = false, onValidationError, validationErrorFallback, loadingOverlay, }) {
     const validation = useMemo(() => validateSnapResponse(snap), [snap]);
     const valid = validation.valid;
     const validationMessage = validation.issues[0]?.message;
@@ -44,18 +44,23 @@ export function SnapViewV2Inner({ snap, handlers, loading = false, onValidationE
             return null;
         return (_jsx(_Fragment, { children: validationErrorFallback ?? _jsx(SnapValidationFallback, { message: validationMessage }) }));
     }
-    return (_jsx(SnapViewCoreInner, { snap: snap, handlers: handlers, loading: loading }));
+    return (_jsx(SnapViewCoreInner, { snap: snap, handlers: handlers, loading: loading, loadingOverlay: loadingOverlay }));
 }
-export function SnapViewV2({ snap, handlers, loading = false, appearance = "dark", colors, onValidationError, validationErrorFallback, }) {
-    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapViewV2Inner, { snap: snap, handlers: handlers, loading: loading, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback }) }));
+export function SnapViewV2({ snap, handlers, loading = false, appearance = "dark", colors, onValidationError, validationErrorFallback, loadingOverlay, }) {
+    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapViewV2Inner, { snap: snap, handlers: handlers, loading: loading, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, loadingOverlay: loadingOverlay }) }));
 }
 // ─── SnapCardV2 (card frame + height limits) ─────────
-function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, appearance, plain, }) {
-    const { colors } = useSnapTheme();
+function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, appearance, plain, loadingOverlay, }) {
+    const { colors, mode } = useSnapTheme();
+    const accentHex = resolveAccentHex(snap.theme?.accent, mode);
     const [contentHeight, setContentHeight] = useState(0);
-    const content = (_jsx(SnapViewV2Inner, { snap: snap, handlers: handlers, loading: loading, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback }));
+    const content = (_jsx(SnapViewV2Inner, { snap: snap, handlers: handlers, loading: loading, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, loadingOverlay: null }));
     if (plain) {
-        return content;
+        return (_jsxs(_Fragment, { children: [content, loading
+                    ? loadingOverlay === undefined
+                        ? _jsx(SnapLoadingOverlay, { appearance: mode, accentHex: accentHex })
+                        : loadingOverlay
+                    : null] }));
     }
     const overflowAmount = showOverflowWarning ? contentHeight - SNAP_MAX_HEIGHT : 0;
     return (_jsxs(_Fragment, { children: [_jsxs(View, { style: {
@@ -66,7 +71,11 @@ function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWa
                     maxHeight: showOverflowWarning ? undefined : SNAP_MAX_HEIGHT,
                     overflow: "hidden",
                     minHeight: 120,
-                }, children: [_jsx(View, { collapsable: false, onLayout: (e) => setContentHeight(Math.round(e.nativeEvent.layout.height)), style: { paddingHorizontal: 16, paddingVertical: 16 }, children: content }), showOverflowWarning && contentHeight > SNAP_MAX_HEIGHT && (_jsxs(View, { style: { position: "absolute", top: SNAP_MAX_HEIGHT, left: 0, right: 0, height: overflowAmount, zIndex: 10, pointerEvents: "none" }, children: [_jsx(View, { style: { height: 1, borderTopWidth: 1, borderStyle: "dashed", borderColor: "rgba(255,100,100,0.6)" } }), _jsx(View, { style: { position: "absolute", top: -10, right: 4, backgroundColor: "rgba(0,0,0,0.7)", paddingHorizontal: 4, paddingVertical: 1, borderRadius: 3 }, children: _jsxs(Text, { style: { fontSize: 10, color: "rgba(255,100,100,0.7)", fontFamily: Platform.select({ ios: "Menlo", default: "monospace" }) }, children: [SNAP_MAX_HEIGHT, "px"] }) }), _jsx(View, { style: { flex: 1, backgroundColor: "rgba(255,50,50,0.15)" } })] }))] }), actionError && (_jsx(Text, { style: {
+                }, children: [_jsx(View, { collapsable: false, onLayout: (e) => setContentHeight(Math.round(e.nativeEvent.layout.height)), style: { paddingHorizontal: 16, paddingVertical: 16 }, children: content }), showOverflowWarning && contentHeight > SNAP_MAX_HEIGHT && (_jsxs(View, { style: { position: "absolute", top: SNAP_MAX_HEIGHT, left: 0, right: 0, height: overflowAmount, zIndex: 10, pointerEvents: "none" }, children: [_jsx(View, { style: { height: 1, borderTopWidth: 1, borderStyle: "dashed", borderColor: "rgba(255,100,100,0.6)" } }), _jsx(View, { style: { position: "absolute", top: -10, right: 4, backgroundColor: "rgba(0,0,0,0.7)", paddingHorizontal: 4, paddingVertical: 1, borderRadius: 3 }, children: _jsxs(Text, { style: { fontSize: 10, color: "rgba(255,100,100,0.7)", fontFamily: Platform.select({ ios: "Menlo", default: "monospace" }) }, children: [SNAP_MAX_HEIGHT, "px"] }) }), _jsx(View, { style: { flex: 1, backgroundColor: "rgba(255,50,50,0.15)" } })] })), loading
+                        ? loadingOverlay === undefined
+                            ? _jsx(SnapLoadingOverlay, { appearance: mode, accentHex: accentHex })
+                            : loadingOverlay
+                        : null] }), actionError && (_jsx(Text, { style: {
                     paddingHorizontal: 12,
                     paddingVertical: 8,
                     fontSize: 13,
@@ -75,8 +84,8 @@ function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWa
                         : "rgba(200,0,0,0.8)",
                 }, children: actionError }))] }));
 }
-export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, }) {
-    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV2Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, appearance: appearance, plain: plain }) }));
+export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, }) {
+    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV2Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, appearance: appearance, plain: plain, loadingOverlay: loadingOverlay }) }));
 }
 const cardStyles = StyleSheet.create({
     frameRing: { alignSelf: "stretch" },

package/dist/ui/catalog.js

@@ -50,7 +50,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
         },
         item: {
             props: itemProps,
-            description: "Content row with title and optional description. Children render in the actions slot (right side) — use badge, button, or text elements.",
+            description: "Content row with title and optional description. Children render in the actions slot (right side) — badge, button, and icon elements are all valid. The item itself is not interactive, so avoid navigation-style icons (`chevron-right`, `arrow-right`, `external-link`) that imply the row navigates.",
         },
         item_group: {
             props: itemGroupProps,

package/llms.txt

@@ -68,7 +68,7 @@ Top-level fields: `version` (required, `"1.0"` or `"2.0"`), `theme` (optional, `
 - `title` (string, required, max 100)
 - `description` (string, optional, max 160)
 - `variant` (optional): `"default"`. Default: `"default"`
-- Children render in the actions slot (right side)
+- Children render in the actions slot (right side). Badges, buttons, and icons are all valid — but the item itself is not interactive, so avoid navigation-style icons (`chevron-right`, `arrow-right`, `external-link`) that imply the row navigates.
 
 **progress** — Horizontal progress bar.
 - `value` (number, required, 0 to max)
@@ -165,7 +165,7 @@ Bound to buttons via `on.press`:
 | `open_mini_app` | `target` (URL) | Open as Farcaster mini app |
 | `view_cast` | `hash` (string) | Navigate to a cast |
 | `view_profile` | `fid` (number) | Navigate to a profile |
-| `compose_cast` | `text?`, `channelKey?`, `embeds?` | Open cast composer |
+| `compose_cast` | `text?`, `channelKey?`, `embeds?` | Open cast composer. Put URLs in `embeds`, not `text` |
 | `view_token` | `token` (CAIP-19) | View token in wallet |
 | `send_token` | `token`, `amount?`, `recipientFid?`, `recipientAddress?` | Send token flow |
 | `swap_token` | `sellToken?`, `buyToken?` | Swap token flow |
@@ -174,6 +174,8 @@ Bound to buttons via `on.press`:
 
 `arrow-right`, `arrow-left`, `external-link`, `chevron-right`, `check`, `x`, `alert-triangle`, `info`, `clock`, `heart`, `message-circle`, `repeat`, `share`, `user`, `users`, `star`, `trophy`, `zap`, `flame`, `gift`, `image`, `play`, `pause`, `wallet`, `coins`, `plus`, `minus`, `refresh-cw`, `bookmark`, `thumbs-up`, `thumbs-down`, `trending-up`, `trending-down`
 
+`chevron-right`, `arrow-right`, and `external-link` are navigation/disclosure affordances — only use them when the surrounding element actually navigates (e.g. a button bound to `open_url` or `open_snap`). Never place them inside an `item`'s actions slot; `item` is not interactive.
+
 ## Color Palette
 
 `gray`, `blue`, `red`, `amber`, `green`, `teal`, `purple`, `pink`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farcaster/snap",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "Farcaster Snaps 🫰",
   "repository": {
     "type": "git",

package/src/react/index.tsx

@@ -59,6 +59,7 @@ export function SnapCard({
   validationErrorFallback,
   actionError,
   plain = false,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -73,6 +74,8 @@ export function SnapCard({
   actionError?: string | null;
   /** When true, renders without card frame (no border, background, or padding). */
   plain?: boolean;
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   if (snap.version === SPEC_VERSION_2) {
     return (
@@ -87,6 +90,7 @@ export function SnapCard({
         validationErrorFallback={validationErrorFallback}
         actionError={actionError}
         plain={plain}
+        loadingOverlay={loadingOverlay}
       />
     );
   }
@@ -100,6 +104,7 @@ export function SnapCard({
       maxWidth={maxWidth}
       actionError={actionError}
       plain={plain}
+      loadingOverlay={loadingOverlay}
     />
   );
 }

package/src/react/snap-view-core.tsx

@@ -8,6 +8,7 @@ import { resolveSnapPaletteHex } from "./lib/resolve-palette-hex";
 import { snapPreviewPrimaryCssProperties } from "./lib/preview-primary-css";
 import {
   type CSSProperties,
+  type ReactNode,
   useCallback,
   useEffect,
   useMemo,
@@ -111,7 +112,7 @@ function ConfettiOverlay() {
   );
 }
 
-function SnapLoadingOverlay({
+export function SnapLoadingOverlay({
   appearance,
   accentHex,
   active,
@@ -197,11 +198,17 @@ export function SnapViewCore({
   handlers,
   loading = false,
   appearance = "dark",
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
   loading?: boolean;
   appearance?: "light" | "dark";
+  /**
+   * Custom content rendered while `loading` is true. When `undefined` (default)
+   * the built-in spinner + backdrop is used. Pass `null` to render nothing.
+   */
+  loadingOverlay?: ReactNode;
 }) {
   const spec = snap.ui;
   const initialState = useMemo(() => spec.state ?? { inputs: {} }, [spec]);
@@ -315,11 +322,15 @@ export function SnapViewCore({
   return (
     <div style={{ position: "relative", width: "100%" }}>
       {showConfetti && <ConfettiOverlay />}
-      <SnapLoadingOverlay
-        appearance={appearance}
-        accentHex={accentHex}
-        active={loading}
-      />
+      {loadingOverlay === undefined ? (
+        <SnapLoadingOverlay
+          appearance={appearance}
+          accentHex={accentHex}
+          active={loading}
+        />
+      ) : loading ? (
+        <>{loadingOverlay}</>
+      ) : null}
 
       <div style={previewSurfaceStyle}>
         <SnapPreviewAccentProvider

package/src/react/v1/snap-view.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import { useEffect, useRef, useState } from "react";
-import { SnapViewCore } from "../snap-view-core";
+import { type ReactNode, useEffect, useMemo, useRef, useState } from "react";
+import { SnapViewCore, SnapLoadingOverlay } from "../snap-view-core";
+import { resolveSnapPaletteHex } from "../lib/resolve-palette-hex";
 import type { SnapPage, SnapActionHandlers } from "../index";
 
 const SNAP_MAX_HEIGHT = 500;
@@ -11,11 +12,14 @@ export function SnapViewV1({
   handlers,
   loading = false,
   appearance = "dark",
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
   loading?: boolean;
   appearance?: "light" | "dark";
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   return (
     <SnapViewCore
@@ -23,6 +27,7 @@ export function SnapViewV1({
       handlers={handlers}
       loading={loading}
       appearance={appearance}
+      loadingOverlay={loadingOverlay}
     />
   );
 }
@@ -35,6 +40,7 @@ export function SnapCardV1({
   maxWidth = 480,
   actionError,
   plain = false,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -43,6 +49,8 @@ export function SnapCardV1({
   maxWidth?: number;
   actionError?: string | null;
   plain?: boolean;
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   const isDark = appearance === "dark";
   const borderColor = isDark ? "rgba(255,255,255,0.1)" : "rgba(0,0,0,0.1)";
@@ -86,6 +94,11 @@ export function SnapCardV1({
 
   const isClipped = isExpandable && !isExpanded;
 
+  const accentHex = useMemo(
+    () => resolveSnapPaletteHex(snap.theme?.accent ?? "purple", appearance),
+    [snap.theme?.accent, appearance],
+  );
+
   return (
     <div
       style={{
@@ -116,9 +129,19 @@ export function SnapCardV1({
             handlers={handlers}
             loading={loading}
             appearance={appearance}
+            loadingOverlay={null}
           />
         </div>
       </div>
+      {loadingOverlay === undefined ? (
+        <SnapLoadingOverlay
+          appearance={appearance}
+          accentHex={accentHex}
+          active={loading}
+        />
+      ) : loading ? (
+        <>{loadingOverlay}</>
+      ) : null}
       {isExpandable ? (
         <div
           style={{

package/src/react/v2/snap-view.tsx

@@ -3,7 +3,8 @@
 import { type ReactNode, useEffect, useMemo } from "react";
 import { validateSnapResponse } from "../../validator.js";
 import type { ValidationResult } from "../../validator.js";
-import { SnapViewCore } from "../snap-view-core";
+import { SnapViewCore, SnapLoadingOverlay } from "../snap-view-core";
+import { resolveSnapPaletteHex } from "../lib/resolve-palette-hex";
 import type { SnapPage, SnapActionHandlers } from "../index";
 
 const SNAP_MAX_HEIGHT = 500;
@@ -45,6 +46,7 @@ export function SnapViewV2({
   appearance = "dark",
   onValidationError,
   validationErrorFallback,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -52,6 +54,8 @@ export function SnapViewV2({
   appearance?: "light" | "dark";
   onValidationError?: (result: ValidationResult) => void;
   validationErrorFallback?: ReactNode;
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   const validation = useMemo(() => validateSnapResponse(snap), [snap]);
   const valid = validation.valid;
@@ -79,6 +83,7 @@ export function SnapViewV2({
       handlers={handlers}
       loading={loading}
       appearance={appearance}
+      loadingOverlay={loadingOverlay}
     />
   );
 }
@@ -96,6 +101,7 @@ export function SnapCardV2({
   validationErrorFallback,
   actionError,
   plain = false,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -107,12 +113,18 @@ export function SnapCardV2({
   validationErrorFallback?: ReactNode;
   actionError?: string | null;
   plain?: boolean;
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   const maxHeight = showOverflowWarning ? SNAP_WARNING_HEIGHT : SNAP_MAX_HEIGHT;
   const isDark = appearance === "dark";
   const bg = isDark ? "rgba(0,0,0,0.85)" : "rgba(255,255,255,0.9)";
   const borderColor = isDark ? "rgba(255,255,255,0.1)" : "rgba(0,0,0,0.1)";
   const surfaceBg = isDark ? "rgba(255,255,255,0.05)" : "rgba(0,0,0,0.02)";
+  const accentHex = useMemo(
+    () => resolveSnapPaletteHex(snap.theme?.accent ?? "purple", appearance),
+    [snap.theme?.accent, appearance],
+  );
 
   return (
     <>
@@ -138,8 +150,18 @@ export function SnapCardV2({
         appearance={appearance}
         onValidationError={onValidationError}
         validationErrorFallback={validationErrorFallback}
+        loadingOverlay={null}
       />
       </div>
+      {loadingOverlay === undefined ? (
+        <SnapLoadingOverlay
+          appearance={appearance}
+          accentHex={accentHex}
+          active={loading}
+        />
+      ) : loading ? (
+        <>{loadingOverlay}</>
+      ) : null}
       {showOverflowWarning && (
         <div
           style={{

package/src/react-native/index.tsx

@@ -31,6 +31,7 @@ export function SnapCard({
   validationErrorFallback,
   actionError,
   plain = false,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -49,6 +50,8 @@ export function SnapCard({
   actionError?: string | null;
   /** When true, renders without card frame (no border, background, or padding). */
   plain?: boolean;
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   if (snap.version === SPEC_VERSION_2) {
     return (
@@ -64,6 +67,7 @@ export function SnapCard({
         validationErrorFallback={validationErrorFallback}
         actionError={actionError}
         plain={plain}
+        loadingOverlay={loadingOverlay}
       />
     );
   }
@@ -78,6 +82,7 @@ export function SnapCard({
       borderRadius={borderRadius}
       actionError={actionError}
       plain={plain}
+      loadingOverlay={loadingOverlay}
     />
   );
 }

package/src/react-native/snap-view-core.tsx

@@ -2,7 +2,14 @@ import type { Spec } from "@json-render/core";
 import { snapJsonRenderCatalog } from "@farcaster/snap/ui";
 import { SnapCatalogView } from "./catalog-renderer";
 import { useSnapTheme } from "./theme";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import { ActivityIndicator, StyleSheet, View } from "react-native";
 import {
   DEFAULT_THEME_ACCENT,
@@ -66,10 +73,16 @@ export function SnapViewCoreInner({
   snap,
   handlers,
   loading = false,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
   loading?: boolean;
+  /**
+   * Custom content rendered while `loading` is true. When `undefined` (default)
+   * the built-in ActivityIndicator overlay is used. Pass `null` to render nothing.
+   */
+  loadingOverlay?: ReactNode;
 }) {
   const { mode } = useSnapTheme();
   const spec = snap.ui;
@@ -172,19 +185,16 @@ export function SnapViewCoreInner({
 
   return (
     <View style={styles.container}>
-      {loading ? (
-        <View
-          style={[
-            styles.overlay,
-            {
-              backgroundColor:
-                mode === "dark" ? "rgba(0,0,0,0.1)" : "rgba(255,255,255,0.2)",
-            },
-          ]}
-        >
-          <ActivityIndicator size="large" color={accentHex} />
-        </View>
-      ) : null}
+      {loading
+        ? loadingOverlay === undefined
+          ? (
+            <SnapLoadingOverlay
+              appearance={mode}
+              accentHex={accentHex}
+            />
+          )
+          : loadingOverlay
+        : null}
       <SnapCatalogView
         key={pageKey}
         spec={spec}
@@ -199,6 +209,30 @@ export function SnapViewCoreInner({
   );
 }
 
+export function SnapLoadingOverlay({
+  appearance,
+  accentHex,
+}: {
+  appearance: "light" | "dark";
+  accentHex: string;
+}) {
+  return (
+    <View
+      style={[
+        styles.overlay,
+        {
+          backgroundColor:
+            appearance === "dark"
+              ? "rgba(0,0,0,0.1)"
+              : "rgba(255,255,255,0.2)",
+        },
+      ]}
+    >
+      <ActivityIndicator size="large" color={accentHex} />
+    </View>
+  );
+}
+
 const styles = StyleSheet.create({
   container: {
     width: "100%",

package/src/react-native/v1/snap-view.tsx

@@ -1,7 +1,11 @@
-import { useEffect, useState } from "react";
+import { type ReactNode, useEffect, useState } from "react";
 import { View, Text, StyleSheet, Pressable } from "react-native";
 import { SnapThemeProvider, useSnapTheme, type SnapNativeColors } from "../theme";
-import { SnapViewCoreInner } from "../snap-view-core";
+import {
+  SnapLoadingOverlay,
+  SnapViewCoreInner,
+  resolveAccentHex,
+} from "../snap-view-core";
 import type { SnapPage, SnapActionHandlers } from "../types";
 
 const SNAP_MAX_HEIGHT = 500;
@@ -12,13 +16,20 @@ export function SnapViewV1Inner({
   snap,
   handlers,
   loading = false,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
   loading?: boolean;
+  loadingOverlay?: ReactNode;
 }) {
   return (
-    <SnapViewCoreInner snap={snap} handlers={handlers} loading={loading} />
+    <SnapViewCoreInner
+      snap={snap}
+      handlers={handlers}
+      loading={loading}
+      loadingOverlay={loadingOverlay}
+    />
   );
 }
 
@@ -28,16 +39,24 @@ export function SnapViewV1({
   loading = false,
   appearance = "dark",
   colors,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
   loading?: boolean;
   appearance?: "light" | "dark";
   colors?: Partial<SnapNativeColors>;
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   return (
     <SnapThemeProvider appearance={appearance} colors={colors}>
-      <SnapViewV1Inner snap={snap} handlers={handlers} loading={loading} />
+      <SnapViewV1Inner
+        snap={snap}
+        handlers={handlers}
+        loading={loading}
+        loadingOverlay={loadingOverlay}
+      />
     </SnapThemeProvider>
   );
 }
@@ -52,6 +71,7 @@ function SnapCardV1Inner({
   actionError,
   appearance,
   plain,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -60,8 +80,10 @@ function SnapCardV1Inner({
   actionError?: string | null;
   appearance: "light" | "dark";
   plain: boolean;
+  loadingOverlay?: ReactNode;
 }) {
-  const { colors } = useSnapTheme();
+  const { colors, mode } = useSnapTheme();
+  const accentHex = resolveAccentHex(snap.theme?.accent, mode);
   const [contentHeight, setContentHeight] = useState(0);
   const [isExpanded, setIsExpanded] = useState(false);
 
@@ -107,9 +129,15 @@ function SnapCardV1Inner({
                 snap={snap}
                 handlers={handlers}
                 loading={loading}
+                loadingOverlay={null}
               />
             </View>
           </View>
+          {loading
+            ? loadingOverlay === undefined
+              ? <SnapLoadingOverlay appearance={mode} accentHex={accentHex} />
+              : loadingOverlay
+            : null}
           {isExpandable ? (
             <View
               style={[
@@ -170,6 +198,7 @@ export function SnapCardV1({
   borderRadius = 16,
   actionError,
   plain = false,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -179,6 +208,8 @@ export function SnapCardV1({
   borderRadius?: number;
   actionError?: string | null;
   plain?: boolean;
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   return (
     <SnapThemeProvider appearance={appearance} colors={colors}>
@@ -190,6 +221,7 @@ export function SnapCardV1({
         actionError={actionError}
         appearance={appearance}
         plain={plain}
+        loadingOverlay={loadingOverlay}
       />
     </SnapThemeProvider>
   );

package/src/react-native/v2/snap-view.tsx

@@ -2,7 +2,11 @@ import type { ReactNode } from "react";
 import { useEffect, useMemo, useState } from "react";
 import { Platform, StyleSheet, Text, View } from "react-native";
 import { SnapThemeProvider, useSnapTheme, type SnapNativeColors } from "../theme";
-import { SnapViewCoreInner } from "../snap-view-core";
+import {
+  SnapLoadingOverlay,
+  SnapViewCoreInner,
+  resolveAccentHex,
+} from "../snap-view-core";
 import {
   validateSnapResponse,
   type ValidationResult,
@@ -47,12 +51,14 @@ export function SnapViewV2Inner({
   loading = false,
   onValidationError,
   validationErrorFallback,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
   loading?: boolean;
   onValidationError?: (result: ValidationResult) => void;
   validationErrorFallback?: ReactNode;
+  loadingOverlay?: ReactNode;
 }) {
   const validation = useMemo(() => validateSnapResponse(snap), [snap]);
   const valid = validation.valid;
@@ -77,7 +83,12 @@ export function SnapViewV2Inner({
   }
 
   return (
-    <SnapViewCoreInner snap={snap} handlers={handlers} loading={loading} />
+    <SnapViewCoreInner
+      snap={snap}
+      handlers={handlers}
+      loading={loading}
+      loadingOverlay={loadingOverlay}
+    />
   );
 }
 
@@ -89,6 +100,7 @@ export function SnapViewV2({
   colors,
   onValidationError,
   validationErrorFallback,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -97,6 +109,8 @@ export function SnapViewV2({
   colors?: Partial<SnapNativeColors>;
   onValidationError?: (result: ValidationResult) => void;
   validationErrorFallback?: ReactNode;
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   return (
     <SnapThemeProvider appearance={appearance} colors={colors}>
@@ -106,6 +120,7 @@ export function SnapViewV2({
         loading={loading}
         onValidationError={onValidationError}
         validationErrorFallback={validationErrorFallback}
+        loadingOverlay={loadingOverlay}
       />
     </SnapThemeProvider>
   );
@@ -124,6 +139,7 @@ function SnapCardV2Inner({
   actionError,
   appearance,
   plain,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -135,8 +151,10 @@ function SnapCardV2Inner({
   actionError?: string | null;
   appearance: "light" | "dark";
   plain: boolean;
+  loadingOverlay?: ReactNode;
 }) {
-  const { colors } = useSnapTheme();
+  const { colors, mode } = useSnapTheme();
+  const accentHex = resolveAccentHex(snap.theme?.accent, mode);
   const [contentHeight, setContentHeight] = useState(0);
 
   const content = (
@@ -146,11 +164,21 @@ function SnapCardV2Inner({
       loading={loading}
       onValidationError={onValidationError}
       validationErrorFallback={validationErrorFallback}
+      loadingOverlay={null}
     />
   );
 
   if (plain) {
-    return content;
+    return (
+      <>
+        {content}
+        {loading
+          ? loadingOverlay === undefined
+            ? <SnapLoadingOverlay appearance={mode} accentHex={accentHex} />
+            : loadingOverlay
+          : null}
+      </>
+    );
   }
 
   const overflowAmount = showOverflowWarning ? contentHeight - SNAP_MAX_HEIGHT : 0;
@@ -184,6 +212,11 @@ function SnapCardV2Inner({
             <View style={{ flex: 1, backgroundColor: "rgba(255,50,50,0.15)" }} />
           </View>
         )}
+        {loading
+          ? loadingOverlay === undefined
+            ? <SnapLoadingOverlay appearance={mode} accentHex={accentHex} />
+            : loadingOverlay
+          : null}
       </View>
       {actionError && (
         <Text
@@ -216,6 +249,7 @@ export function SnapCardV2({
   validationErrorFallback,
   actionError,
   plain = false,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -228,6 +262,8 @@ export function SnapCardV2({
   validationErrorFallback?: ReactNode;
   actionError?: string | null;
   plain?: boolean;
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   return (
     <SnapThemeProvider appearance={appearance} colors={colors}>
@@ -242,6 +278,7 @@ export function SnapCardV2({
         actionError={actionError}
         appearance={appearance}
         plain={plain}
+        loadingOverlay={loadingOverlay}
       />
     </SnapThemeProvider>
   );

package/src/ui/catalog.ts

@@ -58,7 +58,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
     item: {
       props: itemProps,
       description:
-        "Content row with title and optional description. Children render in the actions slot (right side) — use badge, button, or text elements.",
+        "Content row with title and optional description. Children render in the actions slot (right side) — badge, button, and icon elements are all valid. The item itself is not interactive, so avoid navigation-style icons (`chevron-right`, `arrow-right`, `external-link`) that imply the row navigates.",
     },
     item_group: {
       props: itemGroupProps,