\n
\n ` (change with `as`) |\n| `` | `ImageValue` | `![]()
` |\n\nAll three take a `field` prop and read `name` from it. Pass any extra props (`className`, `loading`, etc.) and they go on the rendered element.\n\n```tsx\n` is scalar-only. Passing a list is a type error:\n\n```tsx\n// ✗ Field is not assignable to Field\n` renders an inline ``, never a heading or paragraph, so you supply the semantic tag around it:\n\n```tsx\n// ✓\n
\n` is the exception: it owns a block element, and `as` picks which one.\n\n```tsx\n// ✓ — default is
{fields.subheading.value ?? 'Built for teams that ship.'}
\n\n// ✓ hide the whole component when the key field is empty\nexport function Banner({ fields }: { fields: Fields<{ message: string }> }) {\n if (!fields.message.value) return null;\n return\n\n```\n\n`name` is only accepted alongside `value`. This is the one place you write it.\n\n```tsx\n// ✗ — redundant, and a type error\n`, a `<meta>` tag, an attribute, or it's behind interaction (a closed accordion, an auto-playing carousel). In Composer you still need something the author can click.\n\n`useInComposer()` tells you which mode you're in:\n\n```tsx\nimport { Field, Image, useInComposer } from '@amplifyup/sdk/react';\n\nexport function HeroBackground({ fields }: { fields: Fields<{ heading: string; image: ImageValue }> }) {\n const inComposer = useInComposer();\n\n return (\n <section\n className=\"hero\"\n style={{ backgroundImage: `url(${fields.image.value?.url ?? ''})` }}\n >\n {/* Live: image is a CSS background. Composer: also render it so it's clickable. */}\n {inComposer ? <Image field={fields.image} className=\"hidden\" /> : null}\n <h1><Field field={fields.heading} /></h1>\n </section>\n );\n}\n```\n\nOther common cases:\n\n```tsx\n// Attribute on the live site, editable in Composer\nconst inComposer = useInComposer();\nreturn (\n <>\n <button aria-label={fields.label.value ?? undefined}>\n <Icon />\n {inComposer ? <Field field={fields.label} /> : null}\n </button>\n </>\n);\n```\n\n```tsx\n// Component that hides itself when empty on live, but stays visible for authors\nexport function Announcement({ fields }: { fields: Fields<{ message: string }> }) {\n const inComposer = useInComposer();\n if (!fields.message.value && !inComposer) return null;\n return <div className=\"announcement\"><Field field={fields.message} /></div>;\n}\n```\n\n```tsx\n// Interaction that fights the canvas — turn it off in Composer\nexport function Carousel({ fields }) {\n const inComposer = useInComposer();\n return (\n <>\n {(fields.slides.value ?? []).map((slide) => (\n <Slide key={slide.id} slide={slide} autoplay={!inComposer} />\n ))}\n </>\n );\n}\n```\n\nRules of thumb:\n\n- The **field component is the source of truth in Composer.** If a field is visible to authors, it must be rendered through `<Field>` / `<RichText>` / `<Image>` in Composer mode, even if the live site reads `.value`.\n- **Don't fork the whole component.** Branch the one element that differs, not the entire return. Two divergent trees drift and the preview stops matching production.\n- **Empty gating uses `inComposer`.** `if (!x.value) return null` is correct for live and wrong for authors — they can't click what isn't rendered. Add `&& !inComposer`.\n- **Don't use it to hide editable text on live.** If the text is visible on the live site, render it with the field component in both modes. `useInComposer` is for content the live markup genuinely can't expose as a field.\n\n```tsx\n// ✗ — heading is visible on live; no reason to fork\n{inComposer ? <Field field={fields.heading} /> : fields.heading.value}\n\n// ✓\n<Field field={fields.heading} />\n```\n\n---\n\n## Lists\n\nEvery object array is a list of records. Each row is a fields object plus a plain `id`. Edit `post.title` in the grid and you are editing the post. Which records are in the list, and their order, is edited in the props panel — not on the canvas.\n\nScalar lists (tags, multi-select) stay plain: `fields.tags` is `Field<string[]>`.\n\n```tsx\nimport { Field, Image, RichText } from '@amplifyup/sdk/react';\n\nexport function LatestPosts({ fields }: { fields: Fields<{ heading: string; posts: Post[] }> }) {\n const posts = fields.posts.value ?? [];\n return (\n <section>\n <h2><Field field={fields.heading} /></h2>\n <ul>\n {posts.map((post) => (\n <li key={post.id}>\n <Image field={post.mainImage} />\n <a href={`/blog/${post.slug}`}>\n <Field field={post.title} />\n </a>\n </li>\n ))}\n </ul>\n </section>\n );\n}\n```\n\n```tsx\n// ✗ — Field expects a scalar, not the list or the row\n<Field field={fields.posts} />\n<Field field={post} />\n\n// ✓ — edit the record through its fields\n<Field field={post.title} />\n<Image field={post.mainImage} />\n```\n\nSearch or load-more rows from `queryContent` are the same shape. Render them with the same components — one renderer for both:\n\n```tsx\nconst posts = hits ?? fields.posts.value ?? [];\nreturn posts.map((post) => (\n <article key={post.id}>\n <h2><Field field={post.title} /></h2>\n </article>\n));\n```\n\n### When a row is editable\n\nA row is editable when the SDK knows which record it came from. That happens automatically in two cases:\n\n| Rows came from | Editable in Composer? |\n| --- | --- |\n| A list prop on your component (curated or query connection) | Yes |\n| `queryContent` using the published spec from `{field}Pagination.spec` | Yes |\n| `queryContent` with a spec you assembled by hand, missing `providerId` or `entity` | No — renders as plain text |\n| Rows you fetched yourself from your CMS and passed in as props | No — renders as plain text |\n\nRead-only rows still render their text on the live site and in Composer. They just aren't clickable, and in development the SDK logs once per field:\n\n```\n[AmplifyUp SDK] title has no write target; rendered read-only.\n```\n\nIf you see that and expected an editable field, the fix is upstream — use the published spec instead of a hand-built one, or bind the list to a connection in Composer. Do not try to add `ref` yourself.\n\n```tsx\n// ✓ — spec comes from the list prop Composer published; rows stay editable\nconst hits = await queryContent({\n trackingId,\n route: '/insights',\n spec: searchSpec(postsPagination, 'title', term),\n});\n\n// ✗ — hand-built spec with no connection behind it; rows render read-only\nconst hits = await queryContent({\n trackingId,\n route: '/insights',\n spec: { providerId: '', entity: '', filter: [], sort: [], limit: 10, offset: 0 },\n});\n```\n\n---\n\n## Slots\n\nA slot is a region where authors drop other components. Render it with `<Slot>`:\n\n```tsx\nimport { Slot } from '@amplifyup/sdk/react';\n\nexport function TwoColumn() {\n return (\n <div className=\"grid grid-cols-2\">\n <div><Slot name=\"left\" /></div>\n <div><Slot name=\"right\" /></div>\n </div>\n );\n}\n```\n\n`<Slot>` takes only `name` and `className`. It reads the slot content from `ComponentContextProvider`, so you never thread a `slots` prop through your component.\n\n```tsx\n// ✗ — Slot has no `slots` prop\n<Slot name=\"left\" slots={slots} />\n\n// ✓\n<Slot name=\"left\" />\n```\n\nSlot names must match the slots declared on the component in AmplifyUp. Slots hold components, not fields — nothing in a slot is read through `fields`.\n\n---\n\n## Do / Don't\n\n| Do | Don't |\n| --- | --- |\n| `<Field field={fields.heading} />` | `<Field field={fields.heading} name=\"heading\" />` |\n| `{fields.heading.value}` for non-visible uses | `{fields.heading}` as a JSX child (it's an object) |\n| `{fields.x.value ?? 'default'}` in your code | expect the SDK to supply default copy |\n| `if (!fields.x.value) return null` to hide a component | wrap `Field` in conditional logic that hides the field in Composer |\n| `<h1><Field … /></h1>` | look for an `as` / `wrapper` prop |\n| `<Field field={post.title} />` in a list | `<Field field={fields.posts} />` or `<Field field={post} />` |\n| `value` + `name` together for computed output | `value` alone, or `name` alone |\n| `<Image field={fields.cover} />` | `<img src={fields.cover.value.url} />` when it should be editable |\n| `queryContent` rows through `<Field field={post.title} />` | treat query rows as raw CMS objects |\n| `spec: searchSpec(postsPagination, …)` from the published list prop | hand-build a `spec` and expect rows to stay editable |\n| `<Slot name=\"left\" />` | `<Slot name=\"left\" slots={slots} />` |\n| let the producer set `ref` | set, copy, or patch `ref` yourself |\n| `useInComposer()` to expose a field the live markup can't (CSS background, attribute, hidden panel) | fork the whole component's return on `inComposer` |\n| `if (!x.value && !inComposer) return null` | `if (!x.value) return null` — authors can't click what isn't rendered |\n\n---\n\n## Console messages\n\nIn development the SDK tells you exactly what is wrong. Production is silent.\n\n| Message | What it means | Fix |\n| --- | --- | --- |\n| `Field expects a scalar field. Did you mean <Field field={post.title} />?` | You passed a list or a whole row to `Field` / `RichText` / `Image` | Pass one scalar field off the row |\n| `title has no write target; rendered read-only.` | A row field the SDK can't trace to a record | Bind the list to a connection, or query with the published spec |\n| `Field value={…} requires name=\"…\" for computed values` | You passed `value` without `name` | Add `name={fields.x.name}` |\n| `Field needs field={fields.yourProp} (or value + name for computed values)` | No binding at all | Pass `field=` |\n| `Slot \"left\" used outside ComponentContextProvider` | The component wasn't wrapped when rendered | Wrap it in `renderComponent` |\n\n---\n\n## Types\n\n```ts\nimport type { Field, Fields, ImageValue } from '@amplifyup/sdk/react';\n\ntype Field<T> = {\n value: T;\n name: string;\n /** Write target — the record this field saves to. Page fields omit it. */\n ref?: { providerId: string; entity: string; id: string };\n /** Row field with no write target — display only in Composer. */\n readOnly?: true;\n};\n\ntype Fields<T> = { [K in keyof T]: /* Field<T[K]>, recursing into objects and lists */ };\n```\n\nDeclare the schema shape once on the component and let inference do the rest:\n\n```ts\ntype HeroFields = Fields<{\n eyebrow: string;\n heading: string;\n body: string; // markdown → use <RichText>\n image: ImageValue; // → use <Image>\n posts: Post[]; // list — each row is Fields<Post> & { id: string }\n tags: string[]; // scalar list — Field<string[]>\n}>;\n\nexport function Hero({ fields }: { fields: HeroFields }) { … }\n```\n\n`fields.heading.value` is `string`. `fields.image.value` is `ImageValue | null`. `fields.posts.value[0]` is `Fields<Post> & { id: string }`. `fields.posts.value[0].title` is `Field<string>` with `ref` pointing at that post.\n\n---\n\n## Content sources\n\n| Mode | Source | When |\n|------|--------|------|\n| Production visitors | Edge `/v1/resolve` | Default |\n| Next.js SSG / ISR | Edge `/v1/routes` then `/v1/resolve` | `generateAmplifyStaticParams` + `fetchPageConfigServer` |\n| Composer preview | Orchestrator (Control Plane) layout provider | `?preview=true` / Composer iframe |\n| Runtime queries | Edge `/v1/query` | `queryContent` — search, load more, pickers |\n\nField envelopes are attached once, when the SDK reads the Edge response. Edge's JSON is raw; you never see it that way if you go through `AmplifyPageContent` or `fetchPageConfigServer`. If you call `fetchEdgeResolve` directly you get raw props and must map them yourself — prefer the documented path.\n\n## Pattern pages (From page)\n\nComponents using Composer **From page** require `pageContext` on the provider (or `init`) so the first paint and first page view include fields. Late `setPageContext` is fine for subsequent events, not for rendering those components.\n\n`resource.key` is the URL param value. If a mapped entity field (for example `post.slug`) does not match that param, the SDK warns and uses the URL param.\n\n```tsx\n<AmplifyUpProvider\n config={{ trackingId: 'your-tracking-id' }}\n pageContext={{\n resourceType: 'post',\n key: slug,\n fields: { title: post.title, slug: post.slug, category: post.category },\n }}\n>\n {children}\n</AmplifyUpProvider>\n```\n\nPass `pageContext` at provider/init for From-page components. Do not wait until after first paint. Fixed (static) page fields still attach to events when `pageContext` is omitted.\n\nThe SDK maps Edge's resolved tree into `layoutTree` and renders it. Edge already applies personalization and CMS projection — the site does not call CMS or Decision APIs for layout. After paint, the overlay calls `POST /v1/select` (or `selectVariants()`) then `/v1/resolve?variants=` so decisions stay on the edge (`clientPersonalization`).\n\n## Runtime queries\n\nPage resolve covers data known at Deploy. For data a visitor asks for — search, load more, a picker — use `queryContent`. The browser asks AmplifyUp, AmplifyUp asks your content source, so no CMS credentials or query syntax live in your site.\n\nMark a query connection **paginated** in Composer and the list prop gains pagination meta, including the published query spec:\n\n```tsx\n'use client';\nimport { queryContent, nextPageSpec, searchSpec } from '@amplifyup/sdk/react';\n\n// next page\nconst more = await queryContent({\n trackingId,\n route: '/insights',\n spec: nextPageSpec(postsPagination),\n});\n\n// search — keep `?q=` as input only; do not read searchParams on the server page\nconst hits = await queryContent({\n trackingId,\n route: '/insights',\n spec: searchSpec(postsPagination, 'title', term),\n});\n```\n\nOnly entities published with that route can be queried, and visitors only see published content. Also available from `@amplifyup/sdk/server`. See the [runtime queries guide](../../docs/sdk-site-setup.md#8-runtime-content-queries).\n\n**Always start from `postsPagination.spec`.** `nextPageSpec` and `searchSpec` do that for you. The spec identifies the connection, and that is what makes the returned rows editable in Composer — see [when a row is editable](#when-a-row-is-editable). A spec you assemble by hand has no connection behind it, so its rows come back read-only.\n\n## Track events\n\n```typescript\nimport { init, page, track, identify } from '@amplifyup/sdk';\n\nawait init({ trackingId: 'your-tracking-id' });\n\npage('/home');\ntrack('Product Viewed', { productId: '123' });\nidentify('user-123', { email: 'user@example.com' });\n```\n\n## Debugging\n\n```js\nAmplifyUp.getStatus()\n```\n\nReact context: `useAmplifyUp()` → `{ pageConfig, loading, error, source, meta }`.\n\n## License\n\nMIT","readmeFilename":"README.md"}