Blockwright stores layouts as JSON arrays of elements. The format matches the container export of popular WordPress page builders, so templates and converters built for that format can be imported.
{
"id": "7c1a2b3",
"elType": "container",
"isInner": false,
"settings": {},
"elements": []
}| Key | Meaning |
|---|---|
id |
Unique id (letters, numbers, _, -). Missing or duplicate ids are replaced on save. |
elType |
container (a Frame) or widget. section and column are accepted and converted to frames. |
widgetType |
For widgets: heading, text-editor, button, image, spacer, divider, html, form. |
isInner |
true for nested frames. Top-level frames are boxed by default; nested frames are full width. |
settings |
Flat key/value settings. Only values that differ from the defaults need to be stored. |
elements |
Children (frames only). |
Limits: 5,000 elements, 24 levels deep, 2 MB.
| Type | Example |
|---|---|
| Slider (size) | { "unit": "px", "size": 24 }; custom CSS: { "unit": "custom", "size": "clamp(2rem, 5vw, 4rem)" } |
| Dimensions (padding, margin, radius, border width) | { "unit": "px", "top": 10, "right": 20, "bottom": 10, "left": 20, "isLinked": false } |
| Gaps | { "unit": "px", "column": 20, "row": 20, "isLinked": true } |
| Link | `{ "url": "/contact", "is_external": "on", "nofollow": "", "custom_attributes": "data-track |
| Media | { "url": "/api/media/file/hero.jpg", "alt": "…", "width": 1600, "height": 900 } |
| Switch | "yes" or "" (forms use "true") |
Add the device suffix to any responsive setting: _tablet, _mobile, and when enabled in Site style _laptop, _tablet_extra, _mobile_extra, _widescreen. Smaller devices inherit from larger ones.
{ "flex_direction": "row", "flex_direction_mobile": "column", "padding_mobile": { "unit": "px", "top": 20, "right": 16, "bottom": 20, "left": 16 } }Reference the Site style instead of fixed values with __globals__:
{
"__globals__": {
"title_color": "globals/colors?id=primary",
"typography_typography": "globals/typography?id=primary"
}
}Custom typography needs the group switch set to custom:
{ "typography_typography": "custom", "typography_font_family": "Sora", "typography_font_size": { "unit": "px", "size": 48 }, "typography_font_weight": "700" }Groups follow the same pattern with their prefix: background_*, border_*, box_shadow_*, text_shadow_* (for example background_background: "gradient", background_color, background_color_b, background_gradient_angle).
__dynamic__ maps a setting to a tag. The setting's static value is used as a fallback.
{
"title": "Fallback title",
"__dynamic__": {
"title": "[bw-tag id=\"x1\" name=\"doc-title\" settings=\"%7B%22after%22%3A%22%20%E2%80%94%20Sale%22%7D\"]"
}
}The settings attribute is URL-encoded JSON. Every text tag accepts before, after and fallback. [legacy-tag …] is also accepted, and common names such as post-title map to Blockwright tags.
| Tag | Returns | Settings |
|---|---|---|
site-title, site-tagline, site-url, site-logo |
text, url, image | — |
doc-title, doc-excerpt, doc-url, doc-id |
text, url | — |
doc-date |
text | type: published/modified, format: short/medium/long/full/iso |
doc-field |
any | path, e.g. hero.title |
featured-image |
image | field (optional) |
archive-title |
text | — |
current-date-time |
text | format |
request-parameter |
text | query_var |
user-info |
text | type: name/email/id |
| Setting | Effect |
|---|---|
_margin, _padding |
Spacing (frames use margin, padding) |
_element_width: inherit / auto / initial + _element_custom_width |
Full, inline or custom width inside a frame |
_flex_align_self, _flex_size, _flex_order_custom |
Flex item behaviour |
_position, _offset_x, _offset_y, _z_index |
Positioning |
_element_id, _css_classes (frames: css_classes) |
HTML id and classes |
_animation: fadeIn, fadeInUp, fadeInDown, fadeInLeft, fadeInRight, zoomIn, slideInUp; animation_duration: fast/slow |
Entrance animation (CSS only) |
hide_desktop, hide_tablet, hide_mobile |
Hide per device |
_background_*, _border_*, _border_radius, _box_shadow_* |
Wrapper styling |
custom_css |
Admin-only CSS; selector targets the element |
container_type (flex/grid), content_width (boxed/full), boxed_width, width, min_height, flex_direction, flex_justify_content, flex_align_items, flex_gap, flex_wrap, grid_columns_grid ({ "unit": "fr", "size": 3 }), grid_rows_grid, grid_gaps, grid_auto_flow, html_tag (div, section, header, footer, main, article, aside, nav, a), link, overflow, plus background_*, border_*, border_radius, box_shadow_*.
| Widget | Main settings |
|---|---|
heading |
title, link, header_size (h1–h6, div, span, p), align, title_color, typography_*, text_shadow_*, title_hover_color, blend_mode |
text-editor |
editor (HTML, cleaned on save), align, text_color, typography_*, paragraph_spacing, link_color, link_hover_color |
button |
text, link, align (incl. justify), size (xs–xl), button_css_id, button_text_color, background_*, hover_color, button_background_hover_color, border_*, border_radius, button_box_shadow_*, text_padding, typography_* |
image |
image, bw_alt, align, caption_source (none/attachment/custom), caption, link_to (none/file/custom), link, bw_priority (load first), bw_sizes, width, space (max width), height, object-fit, opacity, image_border_*, image_border_radius, image_box_shadow_*, caption styles |
spacer |
space |
divider |
style, width, align, color, weight, gap |
html |
html (admins only) |
form |
See below |
{
"form_name": "Contact",
"form_fields": [
{ "custom_id": "name", "field_type": "text", "field_label": "Name", "required": "true", "width": "50", "width_mobile": "100" },
{ "custom_id": "topic", "field_type": "select", "field_label": "Topic", "field_options": "Sales|sales\nSupport|support" },
{
"custom_id": "order",
"field_type": "text",
"field_label": "Order number",
"bw_logic": { "action": "show", "match": "all", "rules": [{ "field": "topic", "operator": "is", "value": "support" }] }
},
{ "custom_id": "hp", "field_type": "honeypot" }
],
"submit_actions": ["save", "email", "redirect"],
"email_to": "owner@example.com",
"redirect_to": { "url": "/thanks?name=[field id=\"name\"]" }
}Field types: text, email, textarea, tel, number, url, date, time, select, radio, checkbox, acceptance, rating, range, password, hidden, html, step, honeypot.
Field settings: custom_id, field_label, placeholder, required, width (100, 80, 75, 66, 60, 50, 40, 33, 25, 20) with _tablet/_mobile, field_options (one per line, Label|value), allow_multiple, inline_list, rows, field_min, field_max, field_step, field_value (default), field_html, acceptance_text, checked_by_default, autocomplete, bw_pattern (regex), bw_error, bw_logic, css_classes, and on step fields previous_button/next_button.
Conditional logic operators: is, is_not, contains, not_contains, is_empty, not_empty, gt, lt. A field can only depend on fields above it.
Actions: save, email (email_to, email_subject, email_content, email_from, email_from_name, email_reply_to, email_to_cc, email_to_bcc), email2 (the same keys with _2), redirect (redirect_to), webhook (webhooks, webhooks_advanced_data), collection (bw_collection, bw_collection_mapping: [{ "field": "email", "target": "email" }]).
Placeholders: [all-fields], [field id="…"], {form_name}, {site_name}, {page_url}, {date}.
Layout and messages: input_size, show_labels, mark_required, button_text, button_size, button_width, button_align, step_type (none, text, number, number_text, progress_bar), step_next_label, step_previous_label, custom_messages + success_message, error_message, server_message, invalid_message, required_field_message.
Style: column_gap, row_gap, label_spacing, label_color, mark_required_color, label_typography_*, html_*, field_text_color, bw_placeholder_color, field_typography_*, field_background_color, field_border_color, field_border_width, field_border_radius, bw_field_padding, bw_field_height, bw_field_shadow_*, bw_field_focus_border_color, bw_field_focus_ring_color, bw_field_focus_background, bw_choice_accent, bw_choice_size, bw_choice_gap, bw_rating_color, button_typography_*, button_border_*, button_border_radius, button_text_padding, button_background_color, button_text_color, hover and previous-button colors, hover_transition_duration, message_typography_*, success_message_color, error_message_color, inline_message_color, and step colors and sizes (step_*, steps_*).
Stored as strings on templates:
| Condition | Matches | Priority |
|---|---|---|
include/general |
Entire site | 100 |
include/archive |
All archives and search | 80 |
include/archive/<collection> |
One collection's archive | 70 |
include/archive/search |
Search results | 70 |
include/singular |
Every single document | 60 |
include/singular/<collection> |
Every document in a collection | 50 |
include/singular/<collection>/in/<field>/<id> |
Documents related to <id> through <field> |
40 |
include/front_page |
The front page | 30 |
include/not_found404 |
The 404 page | 20 |
include/singular/<collection>/<id> |
One document | 10 |
exclude/… with the same paths removes a template where it would otherwise show. When several templates match, the lowest priority number wins, then the most recently updated.