Custom AddOn Types
What Are Custom AddOn Types?
Custom AddOn Types define what kind of content your AddOn will insert into the Beefree email builder when users interact with it. Each type corresponds to a specific content module in the Beefree editor, such as images, buttons, paragraphs, or HTML blocks.
Think of AddOn Types as the "shape" of the content your AddOn produces. When you create a Custom AddOn in the Beefree SDK Developer Console, you must select a type that determines:
What content structure is inserted on the stage
Which sidebar properties appear when the module is selected
What schema your AddOn must use when resolving content
How users can edit the inserted content
How AddOn Types Work
1. Type Selection in Console
When creating a Custom AddOn in the Beefree SDK Developer Console, you select a Type from a dropdown menu. This type is permanently associated with your AddOn.
Create Custom AddOn Form:
├── Name: "My Custom AddOn"
├── Type: [Image ▼] ← You select the type here
│ - Image
│ - HTML
│ - Mixed
│ - Row
│ - Paragraph
│ - Button
│ - Title
│ - List
│ - Menu
│ - Icon
├── Handle: "my-custom-addon"
└── ...2. Content Object Schema
Each type requires a specific content object structure that your AddOn must return. This object is passed to the resolve() function in your handler.
Example: Image Type
resolve({
type: 'image', // Must match your AddOn type
value: {
src: 'https://example.com/image.jpg', // Type-specific properties
alt: 'Description'
}
});Example: Button Type
resolve({
type: 'button', // Must match your AddOn type
value: {
label: 'Click Me', // Type-specific properties
href: 'https://example.com',
'background-color': '#7747FF',
color: '#FFFFFF',
'border-radius': 4,
'padding-top': 12,
'padding-right': 24,
'padding-bottom': 12,
'padding-left': 24
}
});3. Editor Integration
When a user drops your AddOn tile onto the stage:
Content Dialog Opens (if using Content Dialog method) or Iframe Loads (if using Iframe method)
User Interacts with your custom UI to create/select content
Your Handler Resolves with a properly formatted content object
Module Is Inserted on the editor stage
Sidebar Updates to show properties specific to that type
User Action Your Code Editor Result
───────────────────────────────────────────────────────────────
Drop AddOn tile → handler() called → Dialog opens
User clicks save → resolve({ → Module appears
type: 'image', on stage
value: {...}
}) → Sidebar shows
image properties4. Sidebar Properties
Each type displays different properties in the editor's sidebar when the module is selected:
Image
Image source, alt text, link, dimensions, alignment
HTML
HTML content (read-only via AddOn), padding, background
Button
Button text, link, colors, borders, padding, alignment
Paragraph
Text editor, font, colors, alignment, spacing
Title/Heading
Heading level, text, font, size, alignment
List
List type, items, font, colors, alignment
Menu
Menu items, links, layout, spacing
Icon
Icon images, links, sizes, alignment
Mixed
Varies based on included modules
Row
Column structure, background, padding, alignment
Available Custom AddOn Types
Beefree SDK currently supports 10 Custom AddOn Types. Each type serves different use cases and content needs.
Content Module Types
These types insert individual content modules:
Image AddOn
Inserts an image module with a source URL, alt text, and optional link.
Resolve Structure:
{
type: 'image',
value: {
src: string,
alt: string,
href: string, // Optional
target: string // Optional: '_blank', '_self'
}
}HTML AddOn
Inserts custom HTML markup. Content is only editable by reopening the AddOn.
Resolve Structure:
{
type: 'html',
value: {
html: string
}
}Paragraph AddOn
Inserts text paragraphs with formatting and support for merge tags.
Resolve Structure:
{
type: 'paragraph',
value: {
html: string,
color: string, // Optional
bold: boolean, // Optional
italic: boolean, // Optional
underline: boolean // Optional
},
mergeTags: [...] // Optional
}Button AddOn
Inserts pre-styled call-to-action buttons.
Resolve Structure:
{
type: 'button',
value: {
label: string,
href: string,
'background-color': string,
color: string,
'border-radius': number, // Pixels (e.g., 4)
'padding-top': number, // Optional, pixels
'padding-right': number, // Optional, pixels
'padding-bottom': number, // Optional, pixels
'padding-left': number // Optional, pixels
}
}Title/Heading AddOn
Inserts heading elements (H1-H3) with custom styling.
Resolve Structure:
{
type: 'heading',
value: {
title: string, // 'h1', 'h2', or 'h3'
text: string, // The heading content
align: string, // 'left', 'center', 'right', 'justify'
size: number, // Font size in pixels
color: string, // Hex color
bold: boolean, // Optional
italic: boolean, // Optional
underline: boolean, // Optional
linkColor: string, // Optional, hex color
'letter-spacing': number, // Optional, -99 to 99
'line-height': number, // Optional, 0.5 to 3
direction: string // Optional, 'ltr' or 'rtl'
}
}Important: Use type: 'heading' in your code, not type: 'title'. The Console may display "Title" but the content object type must be 'heading'.
List AddOn
Inserts ordered or unordered lists with formatting.
Resolve Structure:
{
type: 'list',
value: {
tag: string, // 'ul' or 'ol'
html: string, // The list HTML
color: string, // Optional, hex color
align: string, // Optional, 'left', 'center', 'right'
size: number // Optional, font size in pixels
}
}Menu AddOn
Inserts navigation menus with multiple linked items.
Resolve Structure:
{
type: 'menu',
value: {
items: [
{
text: string,
link: {
href: string,
target: string, // '_blank', '_self'
title: string // Optional
}
}
]
}
}Icon AddOn
Inserts icon sets with images, labels, and links.
Resolve Structure:
{
type: 'icons',
value: {
icons: [
{
image: string, // Icon image URL
text: string, // Icon label
href: string, // Link URL
target: string, // '_blank', '_self'
alt: string, // Alt text
width: string, // e.g., '32px'
height: string, // e.g., '32px'
textPosition: string // 'top', 'bottom', 'left', 'right'
}
]
}
}Advanced Structure Types
These types insert more complex structures:
Mixed Content AddOn
Inserts multiple content modules at once in a single drop action.
Resolve Structure:
{
type: 'mixed',
value: [
{ type: 'image', value: {...} },
{ type: 'heading', value: {...} },
{ type: 'paragraph', value: {...} },
{ type: 'button', value: {...} }
]
}Row AddOn
Inserts a pre-built row structure with columns and multiple modules.
Resolve Structure:
{
type: 'rowAddon',
value: {
name: string,
columns: [
{
weight: number, // Column width (1-12)
modules: [
{ type: 'image', value: {...} },
{ type: 'heading', value: {...} }
]
}
],
metadata: {} // Optional
}
}Validation and Errors
Each type has a specific schema that must be followed. If your resolve() function returns an invalid content object:
The module will not be inserted on the stage
An error will be logged to the browser console
The
onErrorcallback inbeeConfigwill be triggered
Always validate your content objects match the expected schema for your type.
Type-Specific Documentation
For detailed information about each type, including:
Complete schema definitions
Working code examples
Implementation guides for both Content Dialog and Iframe methods
Advanced use cases
Best practices
Refer to the individual type pages:
Schema Resources
All Custom AddOn Types follow schemas defined in the Beefree SDK Simple Schema:
GitHub Repository: BeefreeSDK/beefree-sdk-simple-schema
Official Documentation: Beefree SDK Data Structures
Each type has a corresponding JSON schema file in the repository that defines all valid properties and requirements.
Quick Start Example
Here's a minimal example showing how types work:
// In Beefree SDK Console:
// - Name: "Quick Image AddOn"
// - Type: Image ← Select this
// - Handle: "quick-image"
// In your code:
const beeConfig = {
contentDialog: {
addOn: {
handle: 'quick-image', // Must match Console
handler: (resolve, reject, args) => {
// Your AddOn must return type: 'image'
resolve({
type: 'image', // Must match Console type
value: {
src: 'https://example.com/image.jpg',
alt: 'Example Image'
}
});
}
}
}
};Last updated
Was this helpful?