Templatical

Block & Template Defaults ​

Block properties (colors, font sizes, padding, placeholder text, etc.) are hardcoded in factory functions. blockDefaults and templateDefaults let you override these so every new block and template matches your brand out of the box.

Block Defaults ​

Pass a blockDefaults object to init(). Each key maps to a block type and accepts a partial override of that block's properties:

ts
import { init } from '@templatical/editor';

const editor = await init({
  container: '#editor',
  blockDefaults: {
    title: { color: '#000000' },
    paragraph: {},
    button: {
      backgroundColor: '#ff6600',
      textColor: '#ffffff',
      styles: { padding: { top: 20, bottom: 20 } },
    },
    divider: { color: '#eeeeee', thickness: 2 },
    image: { alt: 'Brand image' },
  },
});

Defaults apply when:

  • Dragging a block from the sidebar
  • Calling createAndAddBlock() programmatically

Defaults do not apply when:

  • Duplicating an existing block (the source block's values are preserved)
  • Loading saved content from the API

Placeholder text ​

The text a new block starts with is localized, so blockDefaults is an override of a localized value rather than of an English one:

ts
const editor = await init({
  container: '#editor',
  locale: 'de',
  blockDefaults: {
    // Without these, a new Title reads "Geben Sie Ihren Titel ein" and a new
    // Button "Hier klicken".
    title: { content: '<p>Ihre Überschrift</p>' },
    paragraph: { content: '<p>Ihr Text</p>' },
    button: { text: 'Jetzt kaufen' },
    video: { alt: 'Produktvideo' },
  },
});

title.content and paragraph.content are rich-text HTML — wrap the text in <p>…</p>. Every other field above is a plain string.

Which locale a default follows depends on whether the text is for the author or for the recipient; Internationalization has the table. Values you set here win over both.

Deep Merge Behavior ​

Nested objects are deep-merged, not shallow-replaced. This means you can override a single padding value without losing the rest:

ts
blockDefaults: {
  button: {
    // Only top padding changes. right/bottom/left keep their defaults.
    styles: { padding: { top: 20 } },
    // Same for buttonPadding — only top changes.
    buttonPadding: { top: 16 },
  },
}

Arrays are replaced, not merged. For example, setting table.rows replaces the entire default rows array.

Supported Block Types ​

KeyBlock Type
titleTitle
paragraphParagraph
imageImage
buttonButton
dividerDivider
sectionSection
videoVideo
socialSocial Icons
spacerSpacer
htmlHTML
menuMenu
tableTable

Custom blocks are not affected by blockDefaults. They use their own default values defined in the CustomBlockDefinition field configuration.

TypeScript Type ​

ts
import type { BlockDefaults } from '@templatical/editor';
// or
import type { BlockDefaults } from '@templatical/types';

Each block type key accepts Partial<Omit<BlockType, 'id' | 'type'>> — you can override any property except id and type, which are always generated automatically. See Block Types for the full list of available properties per block.

Template Defaults ​

Pass a templateDefaults object to override the default template settings used when creating a new empty template:

ts
const editor = await init({
  container: '#editor',
  templateDefaults: {
    width: 640,
    backgroundColor: '#f5f5f5',
    fontFamily: 'Helvetica, sans-serif',
    preheaderText: 'Check out our latest news',
  },
});

When Template Defaults Apply ​

  • No content provided — templateDefaults override the hardcoded factory defaults (width: 600, bg: #ffffff, etc.).
  • Content provided — The provided content's settings are used as-is. templateDefaults have no effect.

In other words, templateDefaults are fallbacks for missing content, not overrides for existing content.

Available Settings ​

PropertyDefaultDescription
width600Template width in pixels
backgroundColor#ffffffTemplate background color
fontFamilyArialDefault font family
localeenBCP-47 content language (<html lang>)
direction—"ltr" or "rtl". Unset follows the content language
preheaderText—Email preheader text

TypeScript Type ​

ts
import type { TemplateDefaults } from '@templatical/editor';
// or
import type { TemplateDefaults } from '@templatical/types';

Hiding a Setting ​

templateDefaults sets a starting value; it does not decide whether the author can change it. To take a setting out of the Settings panel, pass an allowlist to templateSettings.fields:

ts
const editor = await init({
  container: '#editor',
  // The author picks a width; locale and preheader come from the application.
  templateSettings: { fields: ['width', 'backgroundColor', 'fontFamily'] },
});

The two compose in one direction only. templateDefaults applies when no content is provided, so it cannot pin a setting on a template you load — set that from the content itself (init({ content }), or your templates provider's load). See Restricting the settings panel for the full list of fields and how cards follow them.

Built-in Default Constants ​

The SDK exports the built-in default values for every block type and template settings as constants. Use these to inspect current defaults, extend them, or build custom presets:

ts
import {
  DEFAULT_BLOCK_DEFAULTS,
  DEFAULT_TEMPLATE_DEFAULTS,
  TITLE_BLOCK_DEFAULTS,
  PARAGRAPH_BLOCK_DEFAULTS,
  BUTTON_BLOCK_DEFAULTS,
} from '@templatical/types';

// Inspect the defaults for a single block type
console.log(TITLE_BLOCK_DEFAULTS);
// { content: '<p>Enter your title</p>', level: 2, color: '#1a1a1a', ... }

// Inspect template defaults
console.log(DEFAULT_TEMPLATE_DEFAULTS);
// { width: 600, backgroundColor: '#ffffff', fontFamily: 'Arial' }

// Build a custom preset by extending a single block's defaults
const myButtonDefaults = {
  ...BUTTON_BLOCK_DEFAULTS,
  backgroundColor: '#ff6600',
  borderRadius: 8,
};

Available Constants ​

Per-block constants — each contains the default property values for that block type (excluding id, type, and styles):

ConstantBlock Type
TITLE_BLOCK_DEFAULTSTitle
PARAGRAPH_BLOCK_DEFAULTSParagraph
IMAGE_BLOCK_DEFAULTSImage
BUTTON_BLOCK_DEFAULTSButton
DIVIDER_BLOCK_DEFAULTSDivider
SECTION_BLOCK_DEFAULTSSection
VIDEO_BLOCK_DEFAULTSVideo
SOCIAL_ICONS_BLOCK_DEFAULTSSocial Icons
SPACER_BLOCK_DEFAULTSSpacer
HTML_BLOCK_DEFAULTSHTML
MENU_BLOCK_DEFAULTSMenu
TABLE_BLOCK_DEFAULTSTable

Combined constants:

ConstantDescription
DEFAULT_BLOCK_DEFAULTSAll block type defaults in a single object (keys match BlockDefaults interface)
DEFAULT_TEMPLATE_DEFAULTSTemplate settings defaults (width, backgroundColor, fontFamily)

These constants are the single source of truth used internally by the factory functions. If you only need to override a few properties, you don't need to reference them — just pass your overrides to blockDefaults and they'll be deep-merged with these values.

Programmatic Usage ​

The underlying factory functions also accept defaults directly:

ts
import { createBlock, createTitleBlock, createParagraphBlock, createDefaultTemplateContent } from '@templatical/types';
import type { BlockDefaults } from '@templatical/types';

// Single block with partial overrides
const title = createTitleBlock({ level: 2, color: '#000' });
const paragraph = createParagraphBlock({ content: '<p>Hello</p>' });

// Via createBlock with full defaults map
const defaults: BlockDefaults = {
  title: { color: '#000000' },
  button: { backgroundColor: '#ff6600' },
};
const block = createBlock('title', defaults);

// Template with custom settings
const content = createDefaultTemplateContent('Helvetica, sans-serif', {
  width: 640,
  backgroundColor: '#f5f5f5',
});