@farcaster/snap 2.3.1 → 2.5.0

package/dist/ui/catalog.d.ts

@@ -186,7 +186,61 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
                 variant: z.ZodOptional<z.ZodEnum<{
                     default: "default";
                 }>>;
-            }, z.core.$strip>;
+                media: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    variant: z.ZodLiteral<"icon">;
+                    name: z.ZodEnum<{
+                        "arrow-right": "arrow-right";
+                        "arrow-left": "arrow-left";
+                        "external-link": "external-link";
+                        "chevron-right": "chevron-right";
+                        check: "check";
+                        x: "x";
+                        "alert-triangle": "alert-triangle";
+                        info: "info";
+                        clock: "clock";
+                        heart: "heart";
+                        "message-circle": "message-circle";
+                        repeat: "repeat";
+                        share: "share";
+                        user: "user";
+                        users: "users";
+                        star: "star";
+                        trophy: "trophy";
+                        zap: "zap";
+                        flame: "flame";
+                        gift: "gift";
+                        image: "image";
+                        play: "play";
+                        pause: "pause";
+                        wallet: "wallet";
+                        coins: "coins";
+                        plus: "plus";
+                        minus: "minus";
+                        "refresh-cw": "refresh-cw";
+                        bookmark: "bookmark";
+                        "thumbs-up": "thumbs-up";
+                        "thumbs-down": "thumbs-down";
+                        "trending-up": "trending-up";
+                        "trending-down": "trending-down";
+                    }>;
+                    color: z.ZodOptional<z.ZodEnum<{
+                        gray: "gray";
+                        blue: "blue";
+                        red: "red";
+                        amber: "amber";
+                        green: "green";
+                        teal: "teal";
+                        purple: "purple";
+                        pink: "pink";
+                        accent: "accent";
+                    }>>;
+                }, z.core.$strict>, z.ZodObject<{
+                    variant: z.ZodLiteral<"image">;
+                    url: z.ZodString;
+                    alt: z.ZodOptional<z.ZodString>;
+                    round: z.ZodOptional<z.ZodBoolean>;
+                }, z.core.$strict>], "variant">>;
+            }, z.core.$strict>;
             description: string;
         };
         item_group: {
@@ -318,6 +372,7 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
                     between: "between";
                     around: "around";
                 }>>;
+                equalWidth: z.ZodOptional<z.ZodBoolean>;
                 columns: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>, z.ZodLiteral<6>]>>;
             }, z.core.$strip>;
             description: string;
@@ -399,6 +454,10 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
                     none: "none";
                     lg: "lg";
                 }>>;
+                cellAspectRatio: z.ZodOptional<z.ZodEnum<{
+                    auto: "auto";
+                    square: "square";
+                }>>;
                 rowHeight: z.ZodOptional<z.ZodNumber>;
                 select: z.ZodOptional<z.ZodEnum<{
                     multiple: "multiple";

package/dist/ui/catalog.js

@@ -42,7 +42,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
         },
         toggle_group: {
             props: toggleGroupProps,
-            description: "Single or multi-select choice group; `name` becomes POST inputs key. mode: single (default) | multiple. Optional label.",
+            description: "Single or multi-select choice group; `name` becomes POST inputs key. The @farcaster/snap React/React Native components choose row/column orientation from option label length, ignoring snap-sent orientation hints.",
         },
         input: {
             props: inputProps,
@@ -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) — 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.",
+            description: "Content row matching shadcn Item: optional media renders on the left, title and optional description render in the content area, and children render in the actions slot (right side). 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,
@@ -78,7 +78,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
         },
         stack: {
             props: stackProps,
-            description: "Layout container — direction: vertical (default) | horizontal. Children are element ids in order. Horizontal stacks use a single flex row so peers stay side-by-side and shrink with min-width 0. Nested stacks participate as flexible row peers. All-button horizontal stacks use an equal N-column grid where N is the number of buttons (1–6). Optional `columns` (`2`–`6`) forces an explicit equal grid for mixed children.",
+            description: "Layout container — direction: vertical (default) | horizontal. Children are element ids in order. Horizontal stacks use a single flex row so peers stay side-by-side and shrink with min-width 0. Nested stacks participate as flexible row peers. For all-button stacks, the @farcaster/snap React/React Native components choose row/column orientation from button label length, ignoring snap-sent direction hints; horizontal button rows use content-proportional widths while filling the container unless `equalWidth: true` is provided to force equal-width cells. Vertical button rows default to a tighter gap when `gap` is omitted.",
         },
         text: {
             props: textProps,

package/dist/ui/cell-grid.d.ts

@@ -25,6 +25,10 @@ export declare const cellGridProps: z.ZodObject<{
         none: "none";
         lg: "lg";
     }>>;
+    cellAspectRatio: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        square: "square";
+    }>>;
     rowHeight: z.ZodOptional<z.ZodNumber>;
     select: z.ZodOptional<z.ZodEnum<{
         multiple: "multiple";

package/dist/ui/cell-grid.js

@@ -1,12 +1,10 @@
 import { z } from "zod";
 import { isSnapHexColorString, PALETTE_COLOR_VALUES } from "../colors.js";
-import { GRID_MIN_COLS, GRID_MAX_COLS, GRID_MIN_ROWS, GRID_MAX_ROWS, GRID_GAP_VALUES, } from "../constants.js";
+import { GRID_MIN_COLS, GRID_MAX_COLS, GRID_MIN_ROWS, GRID_MAX_ROWS, GRID_GAP_VALUES, GRID_CELL_ASPECT_RATIO_VALUES, } from "../constants.js";
 /** Palette name or `#rrggbb`; input is trimmed so palette and hex rules match runtime resolvers. */
 const cellGridCellColorSchema = z.preprocess((v) => (typeof v === "string" ? v.trim() : v), z.union([
     z.enum(PALETTE_COLOR_VALUES),
-    z
-        .string()
-        .refine(isSnapHexColorString, {
+    z.string().refine(isSnapHexColorString, {
         message: "cell_grid cell hex color must be #rrggbb",
     }),
 ]));
@@ -24,6 +22,7 @@ export const cellGridProps = z
     rows: z.number().int().min(GRID_MIN_ROWS).max(GRID_MAX_ROWS),
     cells: z.array(cellGridCellSchema),
     gap: z.enum(GRID_GAP_VALUES).optional(),
+    cellAspectRatio: z.enum(GRID_CELL_ASPECT_RATIO_VALUES).optional(),
     rowHeight: z.number().int().min(8).max(64).optional(),
     select: z.enum(["off", "single", "multiple"]).optional(),
 })

package/dist/ui/index.d.ts

@@ -10,8 +10,8 @@ export { toggleGroupProps } from "./toggle-group.js";
 export type { ToggleGroupProps } from "./toggle-group.js";
 export { inputProps } from "./input.js";
 export type { InputProps } from "./input.js";
-export { itemProps } from "./item.js";
-export type { ItemProps } from "./item.js";
+export { itemProps, itemMediaProps } from "./item.js";
+export type { ItemMediaProps, ItemProps } from "./item.js";
 export { itemGroupProps } from "./item-group.js";
 export type { ItemGroupProps } from "./item-group.js";
 export { iconProps, ICON_NAMES } from "./icon.js";

package/dist/ui/index.js

@@ -5,7 +5,7 @@ export { buttonProps } from "./button.js";
 export { switchProps } from "./switch.js";
 export { toggleGroupProps } from "./toggle-group.js";
 export { inputProps } from "./input.js";
-export { itemProps } from "./item.js";
+export { itemProps, itemMediaProps } from "./item.js";
 export { itemGroupProps } from "./item-group.js";
 export { iconProps, ICON_NAMES } from "./icon.js";
 export { imageProps } from "./image.js";

package/dist/ui/item.d.ts

@@ -1,12 +1,123 @@
 import { z } from "zod";
 export declare const ITEM_VARIANTS: readonly ["default"];
+export declare const ITEM_MEDIA_VARIANTS: readonly ["icon", "image"];
 export declare const ITEM_MAX_TITLE_CHARS = 100;
 export declare const ITEM_MAX_DESCRIPTION_CHARS = 160;
+export declare const ITEM_MAX_MEDIA_ALT_CHARS = 120;
+export declare const itemMediaProps: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    variant: z.ZodLiteral<"icon">;
+    name: z.ZodEnum<{
+        "arrow-right": "arrow-right";
+        "arrow-left": "arrow-left";
+        "external-link": "external-link";
+        "chevron-right": "chevron-right";
+        check: "check";
+        x: "x";
+        "alert-triangle": "alert-triangle";
+        info: "info";
+        clock: "clock";
+        heart: "heart";
+        "message-circle": "message-circle";
+        repeat: "repeat";
+        share: "share";
+        user: "user";
+        users: "users";
+        star: "star";
+        trophy: "trophy";
+        zap: "zap";
+        flame: "flame";
+        gift: "gift";
+        image: "image";
+        play: "play";
+        pause: "pause";
+        wallet: "wallet";
+        coins: "coins";
+        plus: "plus";
+        minus: "minus";
+        "refresh-cw": "refresh-cw";
+        bookmark: "bookmark";
+        "thumbs-up": "thumbs-up";
+        "thumbs-down": "thumbs-down";
+        "trending-up": "trending-up";
+        "trending-down": "trending-down";
+    }>;
+    color: z.ZodOptional<z.ZodEnum<{
+        gray: "gray";
+        blue: "blue";
+        red: "red";
+        amber: "amber";
+        green: "green";
+        teal: "teal";
+        purple: "purple";
+        pink: "pink";
+        accent: "accent";
+    }>>;
+}, z.core.$strict>, z.ZodObject<{
+    variant: z.ZodLiteral<"image">;
+    url: z.ZodString;
+    alt: z.ZodOptional<z.ZodString>;
+    round: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>], "variant">;
 export declare const itemProps: z.ZodObject<{
     title: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     variant: z.ZodOptional<z.ZodEnum<{
         default: "default";
     }>>;
-}, z.core.$strip>;
+    media: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        variant: z.ZodLiteral<"icon">;
+        name: z.ZodEnum<{
+            "arrow-right": "arrow-right";
+            "arrow-left": "arrow-left";
+            "external-link": "external-link";
+            "chevron-right": "chevron-right";
+            check: "check";
+            x: "x";
+            "alert-triangle": "alert-triangle";
+            info: "info";
+            clock: "clock";
+            heart: "heart";
+            "message-circle": "message-circle";
+            repeat: "repeat";
+            share: "share";
+            user: "user";
+            users: "users";
+            star: "star";
+            trophy: "trophy";
+            zap: "zap";
+            flame: "flame";
+            gift: "gift";
+            image: "image";
+            play: "play";
+            pause: "pause";
+            wallet: "wallet";
+            coins: "coins";
+            plus: "plus";
+            minus: "minus";
+            "refresh-cw": "refresh-cw";
+            bookmark: "bookmark";
+            "thumbs-up": "thumbs-up";
+            "thumbs-down": "thumbs-down";
+            "trending-up": "trending-up";
+            "trending-down": "trending-down";
+        }>;
+        color: z.ZodOptional<z.ZodEnum<{
+            gray: "gray";
+            blue: "blue";
+            red: "red";
+            amber: "amber";
+            green: "green";
+            teal: "teal";
+            purple: "purple";
+            pink: "pink";
+            accent: "accent";
+        }>>;
+    }, z.core.$strict>, z.ZodObject<{
+        variant: z.ZodLiteral<"image">;
+        url: z.ZodString;
+        alt: z.ZodOptional<z.ZodString>;
+        round: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>], "variant">>;
+}, z.core.$strict>;
 export type ItemProps = z.infer<typeof itemProps>;
+export type ItemMediaProps = z.infer<typeof itemMediaProps>;

package/dist/ui/item.js

@@ -1,9 +1,35 @@
 import { z } from "zod";
+import { PROGRESS_COLOR_VALUES } from "../colors.js";
+import { ICON_NAMES } from "./icon.js";
 export const ITEM_VARIANTS = ["default"];
+export const ITEM_MEDIA_VARIANTS = ["icon", "image"];
 export const ITEM_MAX_TITLE_CHARS = 100;
 export const ITEM_MAX_DESCRIPTION_CHARS = 160;
-export const itemProps = z.object({
+export const ITEM_MAX_MEDIA_ALT_CHARS = 120;
+const itemIconMediaProps = z
+    .object({
+    variant: z.literal("icon"),
+    name: z.enum(ICON_NAMES),
+    color: z.enum(PROGRESS_COLOR_VALUES).optional(),
+})
+    .strict();
+const itemImageMediaProps = z
+    .object({
+    variant: z.literal("image"),
+    url: z.string(),
+    alt: z.string().max(ITEM_MAX_MEDIA_ALT_CHARS).optional(),
+    round: z.boolean().optional(),
+})
+    .strict();
+export const itemMediaProps = z.discriminatedUnion("variant", [
+    itemIconMediaProps,
+    itemImageMediaProps,
+]);
+export const itemProps = z
+    .object({
     title: z.string().min(1).max(ITEM_MAX_TITLE_CHARS),
     description: z.string().max(ITEM_MAX_DESCRIPTION_CHARS).optional(),
     variant: z.enum(ITEM_VARIANTS).optional(),
-});
+    media: itemMediaProps.optional(),
+})
+    .strict();

package/dist/ui/stack.d.ts

@@ -20,6 +20,7 @@ export declare const stackProps: z.ZodObject<{
         between: "between";
         around: "around";
     }>>;
+    equalWidth: z.ZodOptional<z.ZodBoolean>;
     columns: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>, z.ZodLiteral<6>]>>;
 }, z.core.$strip>;
 export type StackProps = z.infer<typeof stackProps>;

package/dist/ui/stack.js

@@ -6,7 +6,9 @@ export const stackProps = z.object({
     direction: z.enum(STACK_DIRECTIONS).optional(),
     gap: z.enum(STACK_GAPS).optional(),
     justify: z.enum(STACK_JUSTIFY).optional(),
-    /** Horizontal stacks only: fixed column grid (`2`–`6`). Prefer omitting this when children are stacks — they flex as row peers automatically. */
+    /** Horizontal stacks only: make direct children equal width. */
+    equalWidth: z.boolean().optional(),
+    /** Horizontal stacks only: legacy fixed equal-width column count (`2`–`6`). Prefer `equalWidth`. */
     columns: z.union([
         z.literal(2),
         z.literal(3),

package/dist/validator.js

@@ -14,7 +14,10 @@ const URL_TARGET_ACTIONS = new Set([
  */
 function isLoopback(url) {
     const host = url.hostname;
-    return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+    return (host === "localhost" ||
+        host === "127.0.0.1" ||
+        host === "::1" ||
+        host === "[::1]");
 }
 /**
  * Validate a URL string: must be HTTPS (or HTTP on loopback for dev).
@@ -124,6 +127,21 @@ function validateUrls(elements) {
                 });
             }
         }
+        if (el.type === "item" &&
+            el.props?.media &&
+            typeof el.props.media === "object") {
+            const media = el.props.media;
+            if (media.variant === "image" && typeof media.url === "string") {
+                const error = validateUrl(media.url);
+                if (error) {
+                    issues.push({
+                        code: "custom",
+                        message: error,
+                        path: ["ui", "elements", id, "props", "media", "url"],
+                    });
+                }
+            }
+        }
         // Validate action target URLs
         if (el.on) {
             for (const [event, binding] of Object.entries(el.on)) {

package/llms.txt

@@ -64,10 +64,11 @@ Top-level fields: `version` (required, `"1.0"` or `"2.0"`), `theme` (optional, `
 - `aspect` (required): `"1:1"` | `"16:9"` | `"4:3"` | `"9:16"`
 - `alt` (string, optional)
 
-**item** — Content row with title and right-side actions slot.
+**item** — Content row matching shadcn Item: optional left media, content, and right-side actions slot.
 - `title` (string, required, max 100)
 - `description` (string, optional, max 160)
 - `variant` (optional): `"default"`. Default: `"default"`
+- `media` (optional): left-side media. Icon media: `{ "variant": "icon", "name": IconName, "color"?: PaletteColor }`. Image media: `{ "variant": "image", "url": string, "alt"?: string, "round"?: boolean }`.
 - 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.
@@ -97,6 +98,7 @@ Top-level fields: `version` (required, `"1.0"` or `"2.0"`), `theme` (optional, `
 - `rows` (number, required, 2–16)
 - `cells` (array, required): sparse list of `{ row, col, color?: PaletteColor | #rrggbb, content?: string, value?: string (1–30 chars) }`. When `value` is set on a cell, that string is what's written to `inputs[name]` on press/select; otherwise `"row,col"` is used. Use `value` for grids with meaningful labels (calendar days, alphabet letters, region codes) so handlers don't have to reverse-lookup. Use the row/col fallback for true coordinate grids (minesweeper, tic-tac-toe, pixel art).
 - `gap` (optional): `"none"` (0px) | `"sm"` (1px) | `"md"` (2px) | `"lg"` (4px). Default: `"sm"`
+- `cellAspectRatio` (optional): `"auto"` | `"square"`. Default: `"auto"`. Use `"square"` for game boards whose cells must stay square as snap width changes.
 - `rowHeight` (number, optional, 8–64): pixel height per row. Default: 28. Grid height = rows × rowHeight
 - `select` (optional): `"off"` | `"single"` | `"multiple"`. Default: `"off"`. With `select: "off"`, bind `on.press` for press-to-act (each press writes the cell's `value` or `"row,col"` to `inputs[name]` and fires the action). With `"single"` / `"multiple"`, presses accumulate selection state and pair with a separate submit `button` (multi-select joins values with `|`); `on.press` is ignored.
 - Events: `press` — fires on cell press, only when `select: "off"`; `inputs[name]` is set to the pressed cell's `value` (or `"row,col"` fallback) before the bound action runs

package/package.json

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

package/src/button-orientation-utils.ts

@@ -0,0 +1,36 @@
+export type ButtonContentOrientation = "horizontal" | "vertical";
+
+const MAX_HORIZONTAL_TOTAL_LENGTH: Record<number, number> = {
+  2: 20,
+  3: 15,
+  4: 11,
+  5: 8,
+};
+
+function displayLength(label: string): number {
+  return Array.from(label.trim().replace(/\s+/g, " ")).length;
+}
+
+export function getButtonContentOrientation(
+  labels: readonly string[],
+): ButtonContentOrientation {
+  const lengths = labels
+    .map((label) => displayLength(label))
+    .filter((length) => length > 0);
+  const count = lengths.length;
+
+  if (count <= 1) return "horizontal";
+
+  const maxTotalLength = MAX_HORIZONTAL_TOTAL_LENGTH[count] ?? 0;
+
+  if (maxTotalLength === 0) return "vertical";
+
+  const totalLength = lengths.reduce((sum, length) => sum + length, 0);
+  return totalLength <= maxTotalLength ? "horizontal" : "vertical";
+}
+
+export function shouldUseHorizontalButtonContent(
+  labels: readonly string[],
+): boolean {
+  return getButtonContentOrientation(labels) === "horizontal";
+}

package/src/constants.ts

@@ -11,7 +11,7 @@ export const SNAP_PAYLOAD_HEADER = "X-Snap-Payload" as const;
 
 export const MEDIA_TYPE = "application/vnd.farcaster.snap+json" as const;
 
-export const EFFECT_VALUES = ["confetti"] as const;
+export const EFFECT_VALUES = ["confetti", "fireworks"] as const;
 
 // ─── Pixel grid ────────────────────────────────────────
 export const POST_GRID_TAP_KEY = "grid_tap" as const;
@@ -20,6 +20,7 @@ export const GRID_MAX_COLS = 32;
 export const GRID_MIN_ROWS = 2;
 export const GRID_MAX_ROWS = 16;
 export const GRID_GAP_VALUES = ["none", "sm", "md", "lg"] as const;
+export const GRID_CELL_ASPECT_RATIO_VALUES = ["auto", "square"] as const;
 
 // ─── Snap structural limits ───────────────────────────
 export const MAX_ELEMENTS = 64;

package/src/react/components/action-button.tsx

@@ -60,16 +60,17 @@ export function SnapActionButton({
 
   return (
     /**
-     * In a horizontal stack, `flex-1` lets the wrapper share row width with peers.
-     * In a vertical stack, `flex-1` would silently grow the button to fill column
-     * height (1/N distribution when siblings also flex-grow); stick to `w-full`.
+     * In a horizontal stack, `flex-auto` lets the row fill available width while
+     * preserving content-proportional button widths. In a vertical stack, flex
+     * growth would silently stretch button height; stick to `w-full`.
      */
     <div
       className={
         inHorizontalStack
-          ? "w-full min-w-0 flex-1"
+          ? "min-w-0 flex-auto"
           : "w-full min-w-0"
       }
+      style={inHorizontalStack ? { flex: "1 1 auto" } : undefined}
     >
       <Button
         type="button"

package/src/react/components/cell-grid.tsx

@@ -27,6 +27,7 @@ export function SnapCellGrid({
   const gapMap: Record<string, number> = { none: 0, sm: 1, md: 2, lg: 4 };
   const gapPx = gapMap[gap] ?? 1;
   const rowHeight = typeof props.rowHeight === "number" ? props.rowHeight : 28;
+  const squareCells = props.cellAspectRatio === "square";
 
   const name = props.name ? String(props.name) : POST_GRID_TAP_KEY;
   const tapPath = `/inputs/${name}`;
@@ -78,7 +79,9 @@ export function SnapCellGrid({
 
   /** Cells without a palette `color` — subtle fill so empty slots read as tiles. */
   const emptyCellBg =
-    colors.mode === "dark" ? "rgba(255, 255, 255, 0.05)" : "rgba(0, 0, 0, 0.05)";
+    colors.mode === "dark"
+      ? "rgba(255, 255, 255, 0.05)"
+      : "rgba(0, 0, 0, 0.05)";
 
   const cellEls: ReactNode[] = [];
   for (let r = 0; r < rows; r++) {
@@ -110,7 +113,8 @@ export function SnapCellGrid({
             interactive ? "cursor-pointer select-none" : "cursor-default",
           )}
           style={{
-            height: rowHeight,
+            height: squareCells ? undefined : rowHeight,
+            aspectRatio: squareCells ? "1 / 1" : undefined,
             background: bg,
             color: textColor,
             boxShadow: selected

package/src/react/components/item-group.tsx

@@ -3,6 +3,7 @@
 import { Children, type ReactNode, Fragment } from "react";
 import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors";
+import { SnapItemGroupBorderProvider } from "./item-layout-context";
 
 const GAP_MAP: Record<string, string> = {
   none: "gap-0",
@@ -25,22 +26,23 @@ export function SnapItemGroup({
   const colors = useSnapColors();
 
   return (
-    <div
-      className={cn(
-        "flex flex-col",
-        border && "rounded-lg border",
-        gap,
-      )}
-      style={border ? { borderColor: colors.border } : undefined}
-    >
-      {items.map((child, i) => (
-        <Fragment key={i}>
-          {separator && i > 0 && (
-            <div className="h-px" style={{ backgroundColor: colors.border }} />
-          )}
-          {child}
-        </Fragment>
-      ))}
-    </div>
+    <SnapItemGroupBorderProvider value={border}>
+      <div
+        className={cn("flex flex-col", border && "rounded-lg border", gap)}
+        style={border ? { borderColor: colors.border } : undefined}
+      >
+        {items.map((child, i) => (
+          <Fragment key={i}>
+            {separator && i > 0 && (
+              <div
+                className="h-px"
+                style={{ backgroundColor: colors.border }}
+              />
+            )}
+            {child}
+          </Fragment>
+        ))}
+      </div>
+    </SnapItemGroupBorderProvider>
   );
 }

package/src/react/components/item-layout-context.tsx

@@ -0,0 +1,12 @@
+"use client";
+
+import { createContext, useContext } from "react";
+
+const SnapItemGroupBorderContext = createContext(false);
+
+export const SnapItemGroupBorderProvider =
+  SnapItemGroupBorderContext.Provider;
+
+export function useSnapItemGroupHasBorder() {
+  return useContext(SnapItemGroupBorderContext);
+}