Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.
Webstudio Expressions
Use an expression only when a value must be computed at runtime from scoped data. Use direct text and direct prop values for fixed content.
Source Format
Expression-capable MCP fields receive JavaScript expression source as a JSON
string. Send one expression, without a return statement or surrounding
function. For example:
{ "binding": { "type": "expression", "value": "post.title ?? \"Untitled\"" } }
Inside that string, use readable JavaScript syntax rather than serialized JSON.
For object expressions, leave identifier property names unquoted, for example
{ query: queryText, variables: { slug: system.params.slug } }. Quote a property
name only when JavaScript requires it, such as { "published-at": date }. Do
not pass a JSON-stringified object as an expression.
Do not send a fixed prop string as an expression. Use update-props with
type:"string". Page metadata fields contain expression source; for fixed text,
pass a quoted JavaScript string expression such as "Plans". Resource URLs
accept plain fixed strings and normalize them for storage. Expression-only resource headers, search parameters,
and bodies accept { "type": "literal", "value": "fixed text" } when the
value is not dynamic.
Read and read-write bindings
Expression bindings use mode:"read" by default. Use mode:"readwrite" only
for an exact direct path into the frontmatter of an MDX source connected to the
containing Content Block, for example:
{
"binding": {
"type": "expression",
"value": "document.frontmatter.title",
"mode": "readwrite"
}
}
This lets Content mode save a direct edit back to that frontmatter field.
Computed expressions, including fallbacks and concatenation, are always
read-only. The mutation is rejected when the expression is not a direct path or
does not belong to a connected Content Block document. Use the variable name
returned by inspect-instance; do not assume it is document.
For an MDX-backed article, use the query resource to select the Content Block's
source Asset, for example post.data.id. Inside the block, bind article fields
to the block's document parameter, not post.data.properties.title or other
equivalent query-result values. A query binding can display the correct value
without supporting Content-mode edits.
The MDX body is editable through its source mapping. Designer-created elements
outside that body, such as an article header, stay protected unless their text
or supported props have writable frontmatter bindings. Containment in the
Content Block alone is not enough. Use update-text with
expressionBindingMode:"readwrite" for a designed heading's text, and
bind-props with binding.mode:"readwrite" for a supported prop. These target
persistent designed instances, not MDX-generated instances.
Use direct paths for writable bindings, such as
document.frontmatter.title; property access is already safe. Adding ??
fallbacks or formatting makes the expression read-only. Direct bindings through
loaded Markdown or MDX $ref values ending in #frontmatter save to the
referenced file, with its write permissions enforced. For example, editing
document.frontmatter.author.name updates the shared author file, affecting
every article using it while preserving the article's reference. JSON/body
references remain read-only. Image replacement is a supported reference write,
not a write to shared resolved metadata; use the image recipe below.
Make an article image replaceable
For featureImage: { $ref: "./images/hero.png" }, bind the designed Image's
src to document.frontmatter.featureImage.src with explicit mode:"readwrite".
The default read mode renders the image but does not let the Content-mode
editor replace it. A disabled resolved-URL input is expected; the active
Choose source picker is the replacement control.
Use bind-props with the actual Image instance ID and document variable name:
{
"bindings": [
{
"instanceId": "<imageInstanceId>",
"name": "src",
"binding": {
"type": "expression",
"value": "document.frontmatter.featureImage.src",
"mode": "readwrite"
}
},
{
"instanceId": "<imageInstanceId>",
"name": "alt",
"binding": {
"type": "expression",
"value": "document.frontmatter.featureImage.description",
"mode": "read"
}
}
]
}
The picker saves a new $ref in the article. It must not save a resolved URL
string or modify the original shared Asset. Shared alternative text uses
Choose source → asset actions → Settings → Description instead.
If the picker is absent or disabled, first inspect the source binding's mode,
document scope, loaded $ref, and permissions. Do not infer that replacement
is unsupported from a correctly rendered image or the disabled URL input.
Verify the whole article, not just its body
If the user asks for full Content-mode editing, inventory every article field, including the designed header, hero image source, alternative text, captions, author details, dates, reading time, links, and custom-component content. Verify each field through its Content-mode UI, inspect the saved MDX or referenced file, reload, then restore and verify the original value. A valid binding, correct preview, or successful MCP edit is not a UI-editability test. Report each field as passed, failed, or not tested; do not call the article fully editable with required fields missing or untested.
For images, use the recipe above and verify the picker, changed $ref, reload,
and restoration with an approved temporary replacement. Confirm unrelated MDX
and the original shared Asset remain unchanged. A metadata edit or a disabled
URL input does not test image replacement. If the replacement test is not
authorized, record it as not tested rather than passed.
Keep editable values separate from formatting
When a field must be editable in Content mode, do not concatenate its value with labels, units, or punctuation, or wrap it in a template literal, fallback, or formatting call. Keep the value in its own text element with one direct read-write binding. Put the fixed prefix and suffix in separate sibling text elements. Do not mix literal and expression children in the value element.
For example, display reading time as three inline siblings: fixed — ,
an element bound to document.frontmatter.readingTime, and fixed min read.
Set expressionBindingMode:"readwrite" on the middle element with update-text.
The number remains editable while the surrounding wording stays protected.
Preserve spacing and the field's stored type. For dates, prefer a Date Time
component with its date prop bound directly and formatting configured separately.
Do not silently choose a read-only expression to achieve the requested display. If a required transformation has no editable presentation, explain the limitation and ask before making that field read-only. This does not extend the supported write targets or override permissions.
Scope
- Data variables are available on their scope instance and descendants.
- An inner variable with the same name masks the outer variable.
- A scoped resource result is a variable. Read its payload from its result
wrapper, usually
resourceName.data; APIs may nest the desired value deeper. - Collection creates internal
collectionItemandcollectionItemKeyparameters. They are available only to that Collection's descendants. Preserve those generated parameters and do not reuse encoded parameter ids copied from another Collection. - Array Collection iteration exposes the current item. Object iteration exposes the current key and value.
- The built-in
systemcontext is available only where supplied by the runtime. Its documented fields aresystem.origin,system.pathname,system.params, andsystem.search. There is nosystem.path. - Actions expose only their declared arguments, such as
event, plus data that is in scope.
Read list-variables, list-resources, inspect-instance, and existing
bindings before writing an expression. Do not guess identifier names. Syntax is
validated when a mutation is submitted. A valid expression that references an
identifier unavailable in that scope is accepted with a structured warning
containing the field path, source range, affected record, and remediation.
Supported Syntax
Expressions support literals, arrays, objects, property and index access, unary and arithmetic operators, comparisons, logical operators, nullish coalescing, ternaries, and template literals.
Webstudio automatically makes property and index access safe when an
intermediate value is missing. Always write direct access such as
post.author.name or formData.subject; never add optional property access
(?.) to an authored expression. The expression compiler inserts it into
generated JavaScript, so do not copy that generated syntax into a binding. Use
nullish coalescing when the expression needs a fallback value, for example
formData.subject ?? "New message".
Supported string methods:
{{allowedStringMethods}}
Supported array methods:
{{allowedArrayMethods}}
Other values support toString. Arbitrary global functions and arbitrary
method calls are not supported.
Unsupported Syntax
Do not use statements, declarations, functions, arrow functions, classes,
new, this, await, imports, tagged templates, sequence expressions,
increment/decrement, or destructuring assignment. Assignment is allowed only
inside actions. Use an explicit assignment there rather than ++ or --.
Common Examples
- Text:
post.title ?? "Untitled" - Prop:
post.url - Nested API array for Collection:
posts.data.items - Resource URL:
"https://api.example.com/posts?tag=" + filters.tag - Header:
"Bearer " + auth.token - Search parameter:
String(filters.page ?? 1)is not supported because global function calls are forbidden; use(filters.page ?? 1).toString()instead. - Resource body:
{ query: queryText, variables: { slug: system.params.slug } } - Conditional:
featured ? "Featured" : "Standard" - Nested access with a fallback:
post.author.name ?? "Unknown author"
Collections
Whenever an array or object should render repeated UI, call insert-collection
with the complete iterable and one repeated-item JSX root. Do not pass the
response wrapper or one indexed item. The command creates the Collection and
its private item parameters atomically, then renders the item root once per
entry. Bind descendants with expressions such as collectionItem.name; for
object iteration, collectionItemKey contains the current key. Wrap multiple
repeated siblings in one lowercase HTML root such as <div>.
Verification
Inspect every returned expression warning. Correct warnings that indicate a
misspelled or unavailable variable, then run verify-bindings for persisted
syntax, scope, and reference integrity. A warning does not roll back the
mutation, and successful static verification does not prove runtime data has
the expected shape. verify-bindings never executes external resources or
resolves rendered values. Preview representative data, empty/null data, and
Collection item counts; use audit for relevant structural findings.