https://github.com/yoopta-editor/email-builder
Email-Builder based Yoopta
https://github.com/yoopta-editor/email-builder
email-builder email-design email-editor email-marketing email-template frontend javascript open-source react react-email-editor rich-text-editor typescript wysiwyg yoopta-editor
Last synced: 3 months ago
JSON representation
Email-Builder based Yoopta
- Host: GitHub
- URL: https://github.com/yoopta-editor/email-builder
- Owner: yoopta-editor
- Created: 2024-12-03T21:27:01.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-12-10T22:23:38.000Z (10 months ago)
- Last Synced: 2025-06-05T08:01:49.495Z (4 months ago)
- Topics: email-builder, email-design, email-editor, email-marketing, email-template, frontend, javascript, open-source, react, react-email-editor, rich-text-editor, typescript, wysiwyg, yoopta-editor
- Language: TypeScript
- Homepage: https://yoopta.dev/examples/withEmailBuilder/email-builder
- Size: 366 KB
- Stars: 20
- Watchers: 0
- Forks: 2
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# @yoopta/email-builder
Open-source email-builder built on top of the [Yoopta-Editor](https://github.com/yoopta-editor/Email-Builder)
## Installation
```javascript
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
```
## Demo
- https://yoopta.dev/examples/withEmailBuilder/email-builder
## Quick Start
```javascript
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 (
{
// Your image upload logic
return imageUrl;
},
},
// ... other media handlers
}}
/>
);
}
```
## Core Concepts
### Email Template Options
The email template options define the structure and styling of your email:
```javascript
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,
[key: string]: any,
},
},
container?: {
attrs?: {
style?: Record,
[key: string]: any,
},
},
};
```
### Media Handlers
The email builder supports various media types through upload handlers:
```javascript
type MediaUploaders = {
image?: {
upload: (file: File) => Promise,
},
video?: {
upload: (file: File) => Promise,
uploadPoster: (file: File) => Promise,
},
file?: {
upload: (file: File) => Promise,
},
};
```
## Components
### EmailBuilder
The main component that combines the editor and preview functionality.
```ts
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;
};
```
### EmailEditor
The editing interface component.
```ts
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;
};
```
### EmailPreview
The preview component that shows how the email will look.
```ts
type EmailPreviewProps = {
editor: YooEditor;
value: YooptaContentValue;
template?: EmailTemplateOptions;
style?: React.CSSProperties;
className?: string;
};
```
## Creating an Editor Instance
Use `createYooptaEmailEditor` to create a new editor instance with email capabilities:
```javascript
const editor = useMemo(() => createYooptaEmailEditor({
template: EmailTemplateOptions;
}), []);
```
## Generating Email HTML
The editor instance provides a `getEmail` method to generate the final HTML:
```javascript
const emailHTML = editor.getEmail(value, template?);
```
## Best Practices
- **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
## Example: Complete Email Builder Setup
```javascript
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 (
);
}
```
## API Reference
For detailed API reference, please refer to the TypeScript definitions included in the package.
## Contributing
Contributions are welcome! Please read our contributing guide for details on our code of conduct and the process for submitting pull requests.
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Roadmap
More and more Email components will be available soon.
As well as many other tools for more efficient work with the Email-Builder 😼
## Sponsorship
But we can't do it without your support! If Yoopta has helped you in your work, please consider [sponsoring the project](https://github.com/sponsors/Darginec05). Your contribution is of great importance and helps us to continue to innovate. 💕