> ## Documentation Index
> Fetch the complete documentation index at: https://www.courier.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Install the Courier skill before writing code: `npx skills add trycourier/courier-skills`. It carries the verified SDK shapes and the rules you cannot get wrong.
> Authenticate every request with `Authorization: Bearer <API_KEY>`. A workspace has several environments and each has its own keys, which are plain `pk_` strings with no environment prefix. Start with Test.
> Send with `client.send.message` from the Node SDK (`@trycourier/courier` v7 and later, where the client is the default import). Reference a template by its `nt_` id or its alias.
> A send accepts a bare Elemental element list, but storing content on a template requires the top-level elements wrapped in a channel element.
> To translate a template, write one locale at a time with `PUT /notifications/{id}/locales/{localeId}`, which merges into the existing translations. `PUT /notifications/{id}/content` and `PUT /notifications/{id}/elements/{elementId}` overwrite translations along with the content, so send each element's `id` and `locales` back, and first remove every `checksum` and any `locales` key that starts with an underscore.
> Templates and journeys can be built in the Courier app or created through the API. Either way they live in the workspace and are referenced by ID when you send.
> The hosted MCP server is https://mcp.courier.com. For a briefing on what Courier is and when to use it, read https://www.courier.com/llms.txt.
> Prefer the Guides tab for how-do-I questions and the Docs tab for how-does-it-behave questions. The API reference lives under /api-reference.

# Courier Create template editor

> Mount TemplateEditor in your React app, restrict channels, offer variables, control auto-save, render it in a modal, and publish from your own button.

`TemplateProvider` carries auth and template state. `TemplateEditor` renders the editing surface.

```jsx theme={null}
import "@trycourier/react-designer/styles.css";
import { TemplateProvider, TemplateEditor } from "@trycourier/react-designer";

function Designer({ token }) {
  return (
    <TemplateProvider
      templateId="nt_01kx4h2jdafq8bk9aftxak4b40"
      tenantId="acme-corp"
      token={token}
    >
      <TemplateEditor routing={{ method: "single", channels: ["email"] }} />
    </TemplateProvider>
  );
}
```

The provider creates the Template when `templateId` doesn't resolve to one, so a first
render shows an empty editor rather than an error. Issue the `token` from your backend as the
[Courier Create overview](https://www.courier.com/docs/design/embedded-designer/overview.md#issue-a-scoped-token)
describes.

## Restrict the channels

`routing.channels` decides which channel tabs appear. Unlisted channels are hidden from the
customer.

```jsx theme={null}
<TemplateEditor routing={{ method: "all", channels: ["email", "inbox"] }} />
```

Hiding a channel doesn't restrict what the stored Template may contain. A channel your
customer can't see can still be present in content written through the API.

There is also a bare `channels` prop. It is deprecated in favour of `routing.channels` and
scheduled for removal, so pass `routing`. When both are set, `routing.channels` wins.

## Switch templates

Change `templateId` and the provider loads the new Template. The prop sits in an effect
dependency, so no remount or `key` is needed.

```jsx theme={null}
const [templateId, setTemplateId] = useState("nt_01kx4h2jdafq8bk9aftxak4b40");

<TemplateProvider templateId={templateId} tenantId="acme-corp" token={token}>
  <TemplateEditor />
</TemplateProvider>
```

Auto-save runs against the Template that was mounted, so let a pending save settle before
switching. With the default debounce that is 500ms after the last keystroke.

## Publish from your own button

`hidePublish` removes the built-in control. `useTemplateActions` exposes the same action,
so your own button does the same work.

```jsx theme={null}
import { useTemplateActions } from "@trycourier/react-designer";

function PublishButton() {
  const { publishTemplate } = useTemplateActions();
  return <button onClick={() => publishTemplate()}>Publish</button>;
}
```

Call the hook inside the provider. A component rendered outside it has no template state to
act on.

## Control when writes happen

Auto-save is on, debounced 500ms. Turn it off to write on your own schedule.

```jsx theme={null}
<TemplateEditor autoSave={false} />
```

`readOnly` makes the editor read-only across every channel. It disables editing, toolbar
actions, block insertion, drag and drop, and auto-save, which makes it the prop to reach for
when a customer may view a Template but not change it.

## Offer variables

`variables` populates the autocomplete a customer sees after typing `{{`.

```jsx theme={null}
<TemplateEditor variables={{ user: { first_name: "Sarah" }, order: { id: "1234" } }} />
```

**Leaving `variables` unset disables every variable feature.** The toolbar button is hidden,
and typing `{{` creates no variable chip. Pass `variables` to turn autocomplete on.

Two props change how strict that autocomplete is:

* `disableVariablesAutocomplete` drops the dropdown and lets a customer type any name.
* `variableValidation` restricts which names are allowed and says what happens when one
  fails.

`sampleData` is separate. It validates the data path on a loop, and warns when the path
matches no key or doesn't resolve to an array.

## Theme the editor

`theme` takes a theme object or a class name. `colorScheme` selects `light` or `dark`.

```jsx theme={null}
<TemplateEditor theme={{ background: "#ffffff", primary: "#0f62fe" }} colorScheme="dark" />
```

Import `@trycourier/react-designer/styles.css` once in your app. Without it the editor
renders unstyled, which reads as a broken layout rather than a missing import.

## Render inside a modal

The editor is a regular element, so your own dialog can hold it. Two things about the
surrounding app matter.

Give the container a height. The editor fills its parent, and a dialog that sizes to its
content gives it nothing to fill.

**Set `renderToaster` to `false` when your app already renders a Sonner `<Toaster />`.**
The provider renders its own by default, and two on one page means every save message
appears twice.

```jsx theme={null}
<TemplateProvider
  templateId={templateId}
  tenantId="acme-corp"
  token={token}
  renderToaster={false}
>
  <TemplateEditor />
</TemplateProvider>
```

Keep the provider mounted while the dialog is open. Unmounting it discards template state,
so the next open refetches.

## Provider props

`TemplateProvider` holds auth, identity, and the options that outlive a single editor.

| Property | Type | Required | Description |
| - | - | - | - |
| `templateId` | string | Yes | The Template to edit. Created when it doesn't exist. Changing it loads another Template. |
| `tenantId` | string | Yes | The Tenant the Template belongs to. |
| `token` | string | Yes | JWT authorizing the requests. Issue it server-side, because a browser holding your API key has access to the whole workspace. |
| `apiUrl` | string | No | Override the API base URL. |
| `uploadImage` | `UploadImageFunction` | No | Replace the default image upload. Takes a `Blob`, a `File`, or an `ImageUploadConfig`. |
| `variables` | `Record<string, unknown>` | No | Variables offered to autocomplete. |
| `disableVariablesAutocomplete` | boolean | No | Let customers type any variable name. |
| `variableValidation` | `VariableValidationConfig` | No | Restrict allowed variable names and set the failure behavior. |
| `sampleData` | `Record<string, unknown>` | No | Payload used to validate loop data paths. |
| `renderToaster` | boolean | No | Render the bundled Sonner `<Toaster />`. Defaults to `true`. |

## Editor props

| Property | Type | Default | Description |
| - | - | - | - |
| `autoSave` | boolean | `true` | Save changes automatically. |
| `autoSaveDebounce` | number | `500` | Milliseconds to wait before an auto-save. |
| `brandEditor` | boolean | `false` | Show the brand editor beside the template editor. |
| `brandProps` | `BrandEditorProps` | None | Options passed to that brand editor. |
| `colorScheme` | `"light" \| "dark"` | None | Force a color scheme. |
| `disableVariablesAutocomplete` | boolean | `false` | Let customers type any variable name. |
| `hidePublish` | boolean | `false` | Hide the built-in Publish button. |
| `onChange` | `(value: ElementalContent) => void` | None | Fires when content changes. |
| `readOnly` | boolean | `false` | Make every channel read-only and stop auto-save. |
| `routing` | `MessageRouting` | All channels | Restrict which channel tabs appear. |
| `sampleData` | `Record<string, unknown>` | None | Validate loop data paths against this payload. |
| `theme` | `Theme` or class name | None | Style the editor. |
| `value` | `ElementalContent` | `null` | Initial content. |
| `variables` | `Record<string, unknown>` | None | Variables offered to autocomplete. Unset disables variables entirely. |
| `variableValidation` | `VariableValidationConfig` | None | Restrict allowed variable names. |
| `channels` | `ChannelType[]` | None | Deprecated. Use `routing.channels`. |

## Verify

Render the page and confirm the editor appears. Type into a block, wait for the save
message, then open [Templates](https://app.courier.com/content/templates)
and confirm the Tenant's Template carries the change.

## Troubleshooting

| Symptom | Cause |
| - | - |
| The editor renders unstyled | `@trycourier/react-designer/styles.css` was never imported. |
| The editor has no height | The parent sizes to its content. The editor fills its parent. |
| No variable button, and `{{` does nothing | `variables` is unset, which disables the whole feature. |
| Every save message appears twice | Your app renders a Sonner `<Toaster />` too. Set `renderToaster` to `false`. |
| Edits never persist | `autoSave` is `false` with nothing calling a save, or `readOnly` is `true`. |
| A brand change is rejected while content saves | The token carries `notifications` scopes but no `brand` scopes. |
| `useTemplateActions` has no template | The component calling it sits outside `TemplateProvider`. |

## FAQ

> [accordion] How do I switch the customer to a different template?
>
> Change the `templateId` prop on `TemplateProvider`. The prop sits in an effect
> dependency, so the provider loads the new Template without a remount.

> [accordion] Why is there no variable button in the toolbar?
>
> The `variables` prop is unset. Leaving it undefined disables every variable feature,
> including the `{{` autocomplete.

> [accordion] Can the editor run inside a dialog?
>
> A dialog can hold the editor. Give the container an explicit height, and set
> `renderToaster` to `false` if your app already renders a Sonner `<Toaster />`.

> [accordion] Should I use channels or routing.channels?
>
> Pass `routing.channels`. The bare `channels` prop is deprecated and scheduled for
> removal, and `routing.channels` takes priority when both are set.
