Open-source email-builder built on top of the Yoopta-Editor
npm install @yoopta/email-builder slate slate-react slate-dom
# or
yarn add @yoopta/email-builder slate slate-react slate-dom
# or
pnpm add @yoopta/email-builder slate slate-react slate-dom
import EmailBuilder, { createYooptaEmailEditor } from '@yoopta/email-builder';
import type { YooptaEmailEditor, EmailTemplateOptions } from '@yoopta/email-builder';
// Define your email template options
const templateOptions: EmailTemplateOptions = {
head: {
styles: [
{
id: 'font',
content: `body { font-family: Verdana, sans-serif; }`,
},
],
meta: [{ content: 'width=device-width', name: 'viewport' }, { charset: 'UTF-8' }],
},
body: {
attrs: {
style: {
backgroundColor: '#fafafa',
width: '900px',
margin: '0 auto',
},
},
},
container: {
attrs: {
style: {
width: 600,
margin: '0 auto',
},
},
},
};
function EmailBuilderExample() {
// Initialize the editor
const editor = useMemo(() => createYooptaEmailEditor({ template: templateOptions }), []);
const [value, setValue] = useState({});
return (
<EmailBuilder
editor={editor}
value={value}
onChange={setValue}
media={{
image: {
upload: async (file) => {
// Your image upload logic
return imageUrl;
},
},
// ... other media handlers
}}
/>
);
}
The email template options define the structure and styling of your email:
type EmailTemplateOptions = {
head?: {
styles?: Array<{
id?: string,
content: string,
}>,
meta?: Array<{
content?: string,
name?: string,
charset?: string,
httpEquiv?: string,
property?: string,
}>,
},
body?: {
attrs?: {
style?: Record<string, string | number>,
[key: string]: any,
},
},
container?: {
attrs?: {
style?: Record<string, string | number>,
[key: string]: any,
},
},
};
The email builder supports various media types through upload handlers:
type MediaUploaders = {
image?: {
upload: (file: File) => Promise<string>,
},
video?: {
upload: (file: File) => Promise<string>,
uploadPoster: (file: File) => Promise<string>,
},
file?: {
upload: (file: File) => Promise<string>,
},
};
The main component that combines the editor and preview functionality.
type EmailBuilderProps = {
editor: YooptaEmailEditor;
value: YooptaContentValue;
onChange: (value: YooptaContentValue) => void;
media?: MediaUploaders;
header?: null;
view?: 'editor' | 'preview';
readOnly?: boolean;
autoFocus?: boolean;
placeholder?: string;
className?: string;
style?: React.CSSProperties;
selectionBoxRoot?: HTMLElement | false;
};
The editing interface component.
type EmailEditorProps = {
id: string;
editor: YooEditor;
value: YooptaContentValue;
onChange: (value: YooptaContentValue) => void;
media?: MediaUploaders;
template?: EmailTemplateOptions;
readOnly?: boolean;
autoFocus?: boolean;
placeholder?: string;
selectionBoxRoot?: HTMLElement | false;
};
The preview component that shows how the email will look.
type EmailPreviewProps = {
editor: YooEditor;
value: YooptaContentValue;
template?: EmailTemplateOptions;
style?: React.CSSProperties;
className?: string;
};
Use createYooptaEmailEditor
to create a new editor instance with email capabilities:
const editor = useMemo(() => createYooptaEmailEditor({
template: EmailTemplateOptions;
}), []);
The editor instance provides a getEmail
method to generate the final HTML:
const emailHTML = editor.getEmail(value, template?);
- Email Template Structure
- Always include viewport meta tag
- Define container width for better email client compatibility
- Use web-safe fonts or include font definitions
- Styling
- Use inline styles for better email client compatibility
- Test your email template across different email clients
- Keep the template width between 600-800px for optimal viewing
- Media Handling
- Ensure media upload handlers return absolute URLs
- Implement error handling for failed uploads
- Consider image size optimization for emails
import EmailBuilder, { createYooptaEmailEditor, type EmailTemplateOptions } from '@yoopta/email-builder';
const templateOptions: EmailTemplateOptions = {
head: {
styles: [
{
id: 'font',
content: `body { font-family: Verdana, sans-serif; }`,
},
],
meta: [
{ content: 'width=device-width', name: 'viewport' },
{ charset: 'UTF-8' },
{ content: 'IE=edge', httpEquiv: 'X-UA-Compatible' },
{ content: 'telephone=no,address=no,email=no,date=no,url=no', name: 'format-detection' },
{ content: 'light', name: 'color-scheme' },
],
},
body: {
attrs: {
style: {
backgroundColor: '#fafafa',
width: '900px',
margin: '0 auto',
},
},
},
container: {
attrs: {
style: {
width: 600,
margin: '0 auto',
},
},
},
};
function EmailBuilderExample() {
const editor = useMemo(() => createYooptaEmailEditor({ template: templateOptions }), []);
const [value, setValue] = useState({});
// Example media upload handlers
const mediaUploaders = {
image: {
upload: async (file: File) => {
const url = await uploadImageToServer(file);
return url;
},
},
video: {
upload: async (file: File) => {
const url = await uploadVideoToServer(file);
return url;
},
uploadPoster: async (file: File) => {
const url = await uploadPosterToServer(file);
return url;
},
},
file: {
upload: async (file: File) => {
const url = await uploadFileToServer(file);
return url;
},
},
};
return (
<div className="w-full p-10">
<EmailBuilder editor={editor} value={value} onChange={setValue} media={mediaUploaders} />
</div>
);
}
For detailed API reference, please refer to the TypeScript definitions included in the package.
Contributions are welcome! Please read our contributing guide for details on our code of conduct and the process for submitting pull requests.
This project is licensed under the MIT License - see the LICENSE file for details.
More and more Email components will be available soon. As well as many other tools for more efficient work with the Email-Builder 😼
But we can't do it without your support! If Yoopta has helped you in your work, please consider sponsoring the project. Your contribution is of great importance and helps us to continue to innovate. 💕