Components
Components
API reference for NewsletterBuilder, NewsletterRenderer and the headless useNewsletterEditor hook.
NewsletterBuilder
The complete editor. It owns the document state, so pass initialDocument once and listen with onChange.
NewsletterBuilder props
- Starting document. Read once on mount; change the React
keyto load another document.Default:
blank document - Called after every committed edit. Typing is coalesced so undo steps stay meaningful.
- Runtime customer values applied to the canvas, previews and exported HTML. Not editable in the UI. Change them any time to swap customer data.
- Sample values for previews only. They are never written into exported HTML. Define the object outside the component or memoise it.
Default:
DEFAULT_PREVIEW_DATA - Called when someone edits sample values in the Variables tab.
- Tags offered in the insert-variable menus. Any
{{name}}you type is still compiled.Default:
DEFAULT_MERGE_TAGS - Upload a file to your storage and resolve with a public
https://URL. Without it, uploads becomedata:URLs that are fine for previews but get blocked or clipped by many inboxes. - Notified when someone uses an export button. Useful for analytics.
- Show the dismissible quick-start walkthrough on first load.
Default:
true - Called when the walkthrough is closed. Persist the choice to avoid showing it again.
- Initial tab.
Default:
'edit' - Initial preview colour scheme.
Default:
'light' - Colour theme of the editor chrome itself (not the email).
Default:
'light' - Height of the editor.
Default:
'100%' - Extra class on the root element.
Handling image uploads
<NewsletterBuilder
onImageUpload={async (file) => {
const body = new FormData()
body.set('file', file)
const res = await fetch('/api/upload', { method: 'POST', body })
const { url } = await res.json()
return url // must be a public https URL
}}
/>NewsletterRenderer
Renders a document exactly as it will be exported, in an iframe with sandbox="allow-same-origin allow-popups". Scripts cannot run inside it.
NewsletterRenderer props
- The document to render.
- Always applied. Wins over
previewData. - Sample values for this preview.
darkforces the dark palette so you can preview it on a light page.Default:
'light'- Mobile uses a 375px wide frame.
Default:
'desktop' - Resize the frame to fit the content instead of scrolling inside it.
Default:
false - Accessible title of the iframe.
- Class applied to the iframe.
- Inline styles applied to the iframe.
<NewsletterRenderer
document={doc}
previewData={{ firstName: 'Ada' }}
colorMode="dark"
device="mobile"
autoHeight
/>useNewsletterEditor
The headless state behind the builder. Use it to build your own toolbar, inspector or an automated editing flow.
import { useNewsletterEditor, createBlock, createWelcomeTemplate } from 'newsletter-builder-react'
function MiniEditor() {
const editor = useNewsletterEditor(createWelcomeTemplate(), (doc) => save(doc))
return (
<>
<button onClick={() => editor.appendBlock(createBlock('divider'))}>Add divider</button>
<button onClick={editor.undo} disabled={!editor.canUndo}>Undo</button>
</>
)
}NewsletterEditorApi
- The current document.
- Id of the selected block.
- The selected block.
- Whether history steps are available.
- Insert a block at an explicit location and select it.
- Insert after the selection, or at the end.
- Move a block, including between columns.
- Shallow-merge fields. Pass the same
coalesceKeywhile typing so undo steps merge. - Delete a block.
- Clone a block with fresh ids.
- Move up or down within its list.
- Edit subject and preheader.
- Edit theme settings.
- Replace everything (for example when applying a template). Undoable.
- Change selection.
- Step through history.