@farcaster/snap 2.4.0 → 2.5.0

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.4.0",
+  "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

@@ -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);
+}

package/src/react/components/item.tsx

@@ -6,10 +6,50 @@ import {
   ItemTitle,
   ItemDescription,
   ItemActions,
+  ItemMedia,
 } from "@neynar/ui/item";
 import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors";
 import { useSnapStackDirection } from "../stack-direction-context";
+import { ICON_MAP } from "./icon";
+import { useSnapItemGroupHasBorder } from "./item-layout-context";
+
+type ItemMediaConfig =
+  | {
+      variant: "icon";
+      name: string;
+      color?: string;
+    }
+  | {
+      variant: "image";
+      url: string;
+      alt?: string;
+      round?: boolean;
+    };
+
+function parseItemMedia(value: unknown): ItemMediaConfig | undefined {
+  if (!value || typeof value !== "object") return undefined;
+
+  const media = value as Record<string, unknown>;
+  if (media.variant === "icon" && typeof media.name === "string") {
+    return {
+      variant: "icon",
+      name: media.name,
+      color: typeof media.color === "string" ? media.color : undefined,
+    };
+  }
+
+  if (media.variant === "image" && typeof media.url === "string") {
+    return {
+      variant: "image",
+      url: media.url,
+      alt: typeof media.alt === "string" ? media.alt : undefined,
+      round: typeof media.round === "boolean" ? media.round : undefined,
+    };
+  }
+
+  return undefined;
+}
 
 export function SnapItem({
   element: { props, children: childIds },
@@ -20,26 +60,79 @@ export function SnapItem({
 }) {
   const title = String(props.title ?? "");
   const description = props.description ? String(props.description) : undefined;
+  const media = parseItemMedia(props.media);
   const colors = useSnapColors();
+  const inBorderedGroup = useSnapItemGroupHasBorder();
   const inHorizontalStack = useSnapStackDirection() === "horizontal";
+  const MediaIcon =
+    media?.variant === "icon" ? ICON_MAP[media.name] : undefined;
 
   return (
     <Item
       className={cn(
-        "py-1.5 px-2.5",
+        "gap-2 py-1.5",
+        inBorderedGroup ? "px-2" : "px-0",
         /** Horizontal: share width with peers. Vertical: don't fill column height. */
         inHorizontalStack && "flex-1",
       )}
+      style={{
+        columnGap: 8,
+        paddingInline: inBorderedGroup ? 8 : 0,
+      }}
     >
-      <ItemContent className="gap-0.5">
+      {media?.variant === "icon" && MediaIcon && (
+        <ItemMedia
+          variant="icon"
+          className="self-center translate-y-0"
+          style={{ alignSelf: "center", transform: "none" }}
+        >
+          <MediaIcon
+            size={20}
+            style={{ color: colors.colorHex(media.color) }}
+          />
+        </ItemMedia>
+      )}
+      {media?.variant === "image" && (
+        <ItemMedia
+          variant="image"
+          className="self-center translate-y-0"
+          style={{
+            alignSelf: "center",
+            borderRadius: media.round ? "9999px" : undefined,
+            transform: "none",
+          }}
+        >
+          {/* eslint-disable-next-line @next/next/no-img-element */}
+          <img
+            src={media.url}
+            alt={media.alt ?? ""}
+            className="size-full object-cover"
+          />
+        </ItemMedia>
+      )}
+      <ItemContent className="gap-0">
         <ItemTitle style={{ color: colors.text }}>{title}</ItemTitle>
         {description && (
-          <ItemDescription className="mt-0" style={{ color: colors.textMuted }}>
+          <ItemDescription
+            className="mt-0 text-xs leading-snug"
+            style={{
+              color: colors.textMuted,
+              fontSize: 12,
+              lineHeight: "16px",
+            }}
+          >
             {description}
           </ItemDescription>
         )}
       </ItemContent>
-      {childIds && childIds.length > 0 && <ItemActions>{children}</ItemActions>}
+      {childIds && childIds.length > 0 && (
+        <ItemActions
+          className="gap-1.5 self-center"
+          style={{ alignSelf: "center", columnGap: 6 }}
+        >
+          {children}
+        </ItemActions>
+      )}
     </Item>
   );
 }

package/src/react/components/stack.tsx

@@ -1,11 +1,12 @@
 "use client";
 
-import type { ReactNode } from "react";
+import type { CSSProperties, ReactNode } from "react";
 import { cn } from "@neynar/ui/utils";
 import {
+  childrenShouldUseHorizontalButtonLayout,
+  childrenAreAllButtons,
   countRenderableChildren,
   defaultHorizontalGapSize,
-  horizontalChildrenAreAllButtons,
 } from "../../stack-horizontal-utils.js";
 import {
   SnapStackDirectionProvider,
@@ -14,7 +15,7 @@ import {
 
 const VGAP: Record<string, string> = {
   none: "gap-0",
-  sm: "gap-2",
+  sm: "gap-1",
   md: "gap-4",
   lg: "gap-6",
 };
@@ -34,14 +35,14 @@ const JUSTIFY_FLEX: Record<string, string> = {
   around: "justify-around",
 };
 
-/** Equal columns for explicit `columns` prop and for all-button horizontal rows. */
+/** Equal-width cell count for explicit `equalWidth` / `columns` props. */
 const COLUMN_GRID_CLASS: Record<number, string> = {
-  1: "grid grid-cols-1 auto-rows-auto items-stretch [&>*]:min-w-0",
-  2: "grid grid-cols-2 auto-rows-auto items-stretch [&>*]:min-w-0",
-  3: "grid grid-cols-3 auto-rows-auto items-stretch [&>*]:min-w-0",
-  4: "grid grid-cols-4 auto-rows-auto items-stretch [&>*]:min-w-0",
-  5: "grid grid-cols-5 auto-rows-auto items-stretch [&>*]:min-w-0",
-  6: "grid grid-cols-6 auto-rows-auto items-stretch [&>*]:min-w-0",
+  1: "auto-rows-auto items-stretch [&>*]:min-w-0 [&>*]:w-full",
+  2: "auto-rows-auto items-stretch [&>*]:min-w-0 [&>*]:w-full",
+  3: "auto-rows-auto items-stretch [&>*]:min-w-0 [&>*]:w-full",
+  4: "auto-rows-auto items-stretch [&>*]:min-w-0 [&>*]:w-full",
+  5: "auto-rows-auto items-stretch [&>*]:min-w-0 [&>*]:w-full",
+  6: "auto-rows-auto items-stretch [&>*]:min-w-0 [&>*]:w-full",
 };
 
 export function SnapStack({
@@ -52,17 +53,21 @@ export function SnapStack({
   children?: ReactNode;
 }) {
   const parentDirection = useSnapStackDirection();
-  const direction = String(props.direction ?? "vertical");
+  const buttonContentUsesHorizontal =
+    childrenShouldUseHorizontalButtonLayout(children);
+  const direction =
+    buttonContentUsesHorizontal === undefined
+      ? String(props.direction ?? "vertical")
+      : buttonContentUsesHorizontal
+        ? "horizontal"
+        : "vertical";
   const isHorizontal = direction === "horizontal";
   const justifyKey = props.justify ? String(props.justify) : undefined;
   const justifyFlex = justifyKey ? JUSTIFY_FLEX[justifyKey] : undefined;
-  const buttonRowGrid =
-    isHorizontal && horizontalChildrenAreAllButtons(children);
-  const buttonRowCount = buttonRowGrid
-    ? countRenderableChildren(children)
-    : 0;
+  const allChildrenAreButtons = childrenAreAllButtons(children);
 
   const columnsRaw = props.columns;
+  const equalWidth = props.equalWidth === true;
   const columns =
     typeof columnsRaw === "number" &&
     columnsRaw >= 2 &&
@@ -71,29 +76,36 @@ export function SnapStack({
       ? columnsRaw
       : undefined;
 
-  // Horizontal default depends on column count: 2→lg, 3→md, 4+→sm. Vertical stays md.
-  // Count comes from explicit `columns`, then button-row inference, else direct children
-  // count (any horizontal stack is N columns wide regardless of child types).
-  const horizontalColumnCount = isHorizontal
-    ? (columns ??
-       (buttonRowGrid ? buttonRowCount : undefined) ??
-       countRenderableChildren(children))
+  const equalWidthColumnCount =
+    columns ?? (equalWidth ? countRenderableChildren(children) : undefined);
+  const explicitEqualWidth =
+    isHorizontal &&
+    equalWidthColumnCount !== undefined &&
+    equalWidthColumnCount >= 1 &&
+    equalWidthColumnCount <= 6;
+
+  // Button-only stacks always default to sm; mixed horizontal stacks scale by child count.
+  // Vertical non-button stacks default to md.
+  const horizontalChildCount = isHorizontal
+    ? (explicitEqualWidth
+        ? equalWidthColumnCount
+        : countRenderableChildren(children))
     : undefined;
   const explicitGap =
     typeof props.gap === "string" && props.gap in (isHorizontal ? HGAP : VGAP);
   const gapKey = explicitGap
     ? String(props.gap)
-    : isHorizontal
-      ? defaultHorizontalGapSize(horizontalColumnCount)
+    : allChildrenAreButtons
+      ? "sm"
+      : isHorizontal
+      ? defaultHorizontalGapSize(horizontalChildCount)
       : "md";
   const gap = isHorizontal
     ? (HGAP[gapKey] ?? HGAP.md!)
     : (VGAP[gapKey] ?? VGAP.md!);
-  const explicitColumnGrid =
-    isHorizontal && columns !== undefined && !buttonRowGrid;
   const columnGridClass =
-    explicitColumnGrid && columns !== undefined
-      ? COLUMN_GRID_CLASS[columns]
+    explicitEqualWidth && equalWidthColumnCount !== undefined
+      ? COLUMN_GRID_CLASS[equalWidthColumnCount]
       : undefined;
 
   /**
@@ -108,11 +120,18 @@ export function SnapStack({
 
   const justifyBlockGrid =
     justifyFlex &&
-    (!isHorizontal || (!buttonRowGrid && !explicitColumnGrid));
+    (!isHorizontal || !explicitEqualWidth);
 
   /** Single flex row (nowrap): peers stay side-by-side and shrink via min-w-0 / flex-1 on nested stacks. */
   const horizontalFlexClasses =
     "flex min-w-0 flex-row flex-nowrap items-stretch [&>*]:min-w-0";
+  const equalWidthStyle: CSSProperties | undefined =
+    explicitEqualWidth && equalWidthColumnCount !== undefined
+      ? {
+          display: "grid",
+          gridTemplateColumns: `repeat(${equalWidthColumnCount}, minmax(0, 1fr))`,
+        }
+      : undefined;
 
   return (
     <SnapStackDirectionProvider
@@ -122,20 +141,12 @@ export function SnapStack({
         className={cn(
           rootWidthClass,
           isHorizontal
-            ? buttonRowGrid &&
-                buttonRowCount >= 1 &&
-                buttonRowCount <= 6 &&
-                COLUMN_GRID_CLASS[buttonRowCount]
-              ? cn(
-                  COLUMN_GRID_CLASS[buttonRowCount]!,
-                  gap,
-                  "[&>*]:w-full",
-                )
-              : explicitColumnGrid && columnGridClass
+            ? explicitEqualWidth && columnGridClass
                 ? cn(columnGridClass, gap)
                 : cn(horizontalFlexClasses, gap, justifyBlockGrid ? justifyFlex : undefined)
             : cn("flex min-w-0 w-full flex-col", gap, justifyFlex),
         )}
+        style={equalWidthStyle}
       >
         {children}
       </div>

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

@@ -4,6 +4,7 @@ import { useState } from "react";
 import { useStateStore } from "@json-render/react";
 import { Label } from "@neynar/ui/label";
 import { cn } from "@neynar/ui/utils";
+import { shouldUseHorizontalButtonContent } from "../../button-orientation-utils.js";
 import { useSnapColors } from "../hooks/use-snap-colors";
 
 export function SnapToggleGroup({
@@ -17,7 +18,6 @@ export function SnapToggleGroup({
   const path = `/inputs/${name}`;
   const label = props.label ? String(props.label) : undefined;
   const isMultiple = Boolean(props.multiple);
-  const orientation = String(props.orientation ?? "horizontal");
   const options = Array.isArray(props.options)
     ? (props.options as string[])
     : [];
@@ -50,7 +50,7 @@ export function SnapToggleGroup({
     }
   };
 
-  const isVertical = orientation === "vertical";
+  const isVertical = !shouldUseHorizontalButtonContent(options);
   const [hoveredIdx, setHoveredIdx] = useState<number | null>(null);
 
   return (
@@ -68,14 +68,16 @@ export function SnapToggleGroup({
           const isHovered = hoveredIdx === i && !isSelected;
           return (
             <button
-              key={opt}
+              key={`${opt}-${i}`}
               type="button"
               onClick={() => toggle(opt)}
               onPointerEnter={() => setHoveredIdx(i)}
               onPointerLeave={() => setHoveredIdx(null)}
               className={cn(
                 "rounded-md px-3 py-2 text-sm font-medium transition-colors",
-                isVertical ? "w-full" : "flex-1",
+                isVertical
+                  ? "w-full"
+                  : "flex-auto whitespace-nowrap",
               )}
               style={{
                 transition: "background-color 0.15s, color 0.15s",

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

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

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

@@ -5,6 +5,7 @@ import { Pressable, StyleSheet, Text, View } from "react-native";
 import { ExternalLink } from "lucide-react-native";
 import { useSnapPalette } from "../use-snap-palette";
 import { useSnapTheme } from "../theme";
+import { useSnapStackDirection } from "../stack-direction-context";
 import { ICON_MAP } from "./snap-icon";
 
 function isExternalLinkAction(
@@ -32,12 +33,13 @@ export function SnapActionButton({
 
   const textColor = isPrimary ? "#fff" : colors.text;
   const iconColor = isPrimary ? "#fff" : colors.text;
+  const inHorizontalStack = useSnapStackDirection() === "horizontal";
 
   const on = (element as unknown as { on?: Record<string, unknown> }).on;
   const showExternalIcon = isExternalLinkAction(on);
 
   return (
-    <View style={styles.outer}>
+    <View style={inHorizontalStack ? styles.outerHorizontal : styles.outer}>
       <Pressable
         style={({ pressed }) => [
           styles.btn,
@@ -77,7 +79,18 @@ export function SnapActionButton({
 }
 
 const styles = StyleSheet.create({
-  outer: { minWidth: 0 },
+  outer: {
+    width: "100%",
+    minWidth: 0,
+    alignSelf: "stretch",
+  },
+  outerHorizontal: {
+    flexGrow: 1,
+    flexShrink: 1,
+    flexBasis: "auto",
+    minWidth: 0,
+    alignSelf: "stretch",
+  },
   btn: {
     paddingHorizontal: 16,
     borderRadius: 10,

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

@@ -18,6 +18,7 @@ export function SnapCellGrid({
   const rows = Number(props.rows ?? 2);
   const cells = Array.isArray(props.cells) ? props.cells : [];
   const rowHeight = typeof props.rowHeight === "number" ? props.rowHeight : 28;
+  const squareCells = props.cellAspectRatio === "square";
   const gap = String(props.gap ?? "sm");
   const gapMap: Record<string, number> = { none: 0, sm: 1, md: 2, lg: 4 };
   const gapPx = gapMap[gap] ?? 1;
@@ -101,18 +102,35 @@ export function SnapCellGrid({
 
       // Two-tone ring: outer View with contrasting border, inner View with inverse border
       const cellView = selected ? (
-        <View style={[styles.cell, { height: rowHeight, borderWidth: 1, borderColor: ringOuter, borderRadius: 4 }]}>
+        <View
+          style={[
+            styles.cell,
+            squareCells ? styles.squareCell : { height: rowHeight },
+            { borderWidth: 1, borderColor: ringOuter, borderRadius: 4 },
+          ]}
+        >
           <View
             style={[
               styles.innerCell,
-              { backgroundColor: bg, borderWidth: 1, borderColor: ringInner, borderRadius: 3 },
+              {
+                backgroundColor: bg,
+                borderWidth: 1,
+                borderColor: ringInner,
+                borderRadius: 3,
+              },
             ]}
           >
             {cellContent}
           </View>
         </View>
       ) : (
-        <View style={[styles.cell, { height: rowHeight, backgroundColor: bg }]}>
+        <View
+          style={[
+            styles.cell,
+            squareCells ? styles.squareCell : { height: rowHeight },
+            { backgroundColor: bg },
+          ]}
+        >
           {cellContent}
         </View>
       );
@@ -141,7 +159,17 @@ export function SnapCellGrid({
   }
 
   return (
-    <View style={[styles.wrap, { gap: gapPx, backgroundColor: colors.muted, padding: 4, borderRadius: 8 }]}>
+    <View
+      style={[
+        styles.wrap,
+        {
+          gap: gapPx,
+          backgroundColor: colors.muted,
+          padding: 4,
+          borderRadius: 8,
+        },
+      ]}
+    >
       {rowEls}
     </View>
   );
@@ -156,6 +184,10 @@ const styles = StyleSheet.create({
     alignItems: "center",
     justifyContent: "center",
   },
+  squareCell: {
+    aspectRatio: 1,
+    width: "100%",
+  },
   innerCell: {
     width: "100%",
     height: "100%",