A canvas is Jetstack's custom composition surface. It stores a tree of canvas items and renders them as a custom page, reusable fragment, widget, or property-oriented interface.
Unlike a View, which starts from a query and a viewer, a canvas starts from layout composition. It is the place to use when the screen must be intentionally assembled from multiple blocks, nested surfaces, object context, forms, widgets, and custom rendering.
Canvases are the platform's answer to experience design problems that do not fit comfortably into standard list, form, or module layouts.
Use canvases when:
- one page needs several coordinated regions
- a module needs a custom landing page
- a reusable UI fragment should be embedded inside other canvases
- a widget-like building block should be shared between pages or dashboards
- a property needs a custom visual or entry template, such as a replicator row layout
- a form flow needs a custom arrangement and event-driven automations
There are two layers to understand:
- the canvas resource itself
- the item tree edited in CanvasBuilder
This chapter focuses on the canvas resource and its configuration options, especially the meaning of canvas roles. The item-level builder model is described in:
Use this chapter together with:
Keep these distinctions clear:
- a canvas is the stored container
role describes the intended usage pattern of the canvascontent stores the published item treecontent_draft stores the draft version being edited in CanvasBuilderdraft_saved tells the builder whether an unpublished draft currently existsmeta stores preload automation, meta tags, CSS, and script blocksavailable_to_roles only applies to widget-role canvases
The most important practical point is this:
- the canvas form stores only a small number of top-level fields
- the real experience design happens inside CanvasBuilder
What it is:
- the main administrative name of the canvas
How to configure it:
- enter a stable implementation-facing name such as
Project Dashboard, Opportunity Header Widget, Task Detail Snippet, or Replicator Row Template
Why it matters:
- this is the title-role field for the canvas resource
- it is the main builder label shown in canvas lists and references
- many integrations show this value when asking the user to choose a canvas
Use it when:
- you want a clear internal name that reflects the canvas purpose, not only its visual shape
Good naming guidance:
- include the usage intent in the name
- prefer
Project KPI Widget over just KPI
What it is:
- the display-facing title of the canvas
How to configure it:
- enter the title that should represent the canvas in user-facing contexts
- leave it empty when the same wording as
canvas_name is appropriate
Why it matters:
- some widget integrations and UI surfaces use the title first and fall back to the name if needed
- it lets you keep a more technical builder name while presenting a cleaner label in reusable contexts
Use it when:
- the canvas should have a friendlier or shorter display title than its internal name
What it is:
- the declared usage role of the canvas
How to configure it:
- choose one of:
MainSnippetWidgetProperty
Why it matters:
- roles help organize canvases by intended purpose
- the canvas overview is tabbed by role
- widget-role canvases also participate in role-based availability logic
Important implementation note:
- in the current codebase,
Widget is the only role with strong runtime-specific behavior directly enforced by availability logic
- the other roles are still important, but mostly as conventions, organization, and integration intent rather than hard runtime switches
This makes the role field both semantic and practical:
- semantic for
Main, Snippet, and Property
- semantic plus operational for
Widget
The role meanings are detailed below.
What it is:
- the list of roles allowed to use a widget canvas
How to configure it:
- this field is shown only when
role = Widget
- select the roles that should have the widget available
Why it matters:
- widget canvases are discoverable through the widget system
- the canvas manager filters widget IDs by the current user's roles unless the user is a superuser
Important distinction:
- this option does not appear for non-widget canvases
- it is not a general permission control for all canvas usage modes
Use it when:
- a widget should only be available to certain operational roles
- the same tenant has different dashboards or widget blocks for different audiences
What it is:
- the published serialized canvas item tree
How to configure it:
- do not normally edit this field manually
- build and publish the canvas through CanvasBuilder instead
Why it matters:
- this is the version used for normal runtime rendering
- CanvasControl unserializes this item tree and renders each item into HTML
Practical rule:
- treat
content as managed builder output, not as a normal text field
What it is:
- the current unpublished draft of the canvas item tree
How to configure it:
- it is created and updated automatically by CanvasBuilder while you edit the canvas
Why it matters:
- canvases support a publish workflow
- you can keep editing a draft without replacing the live published version immediately
Use it when:
- you need safe iteration on a live canvas
- you want to compare builder changes mentally before publishing
What it is:
- a flag indicating that the canvas currently has an unpublished draft
How to configure it:
- this is managed by CanvasBuilder
- it becomes true when draft changes are stored
- it is cleared when the draft is discarded or published
Why it matters:
- the builder uses it to decide whether it should load
content_draft or content
- it gives operators a clear signal that the published canvas and the working draft are different
What it is:
- a structured metadata object for canvas-level runtime behavior
How to configure it:
- in normal practice, configure it through the CanvasBuilder meta dialog rather than by hand
What it stores:
automationPreloadmetacssscripts
Why it matters:
- this is where canvas-level preload logic and page-level embellishments live
- it applies to the entire canvas, not only to one item
¶ Main
What it means:
- a main canvas is intended as a primary page-level composition
Typical use cases:
- module landing pages
- full dashboard pages
- custom detail pages
- custom object action pages
Why to choose it:
- it signals that the canvas is meant to stand on its own rather than act as a reusable sub-fragment
How it behaves in the platform:
- it appears in the
Main tab of canvas administration
- it can be referenced from places that render a full canvas, such as module canvas integrations or action-driven object canvas pages
Design guidance:
- choose
Main when the canvas is the destination, not only a component
What it means:
- a snippet canvas is intended as a reusable nested fragment
Typical use cases:
- reusable header sections
- common KPI strips
- standardized sub-panels
- reusable detail blocks shared by several larger canvases
How it behaves in the platform:
- it appears in the
Snippet tab of canvas administration
- it is well suited for embedding through the
Canvas item inside another canvas
Important note:
- the runtime does not currently enforce a unique snippet-only execution model
- this role mainly communicates design intent and helps keep reusable fragment canvases organized
Design guidance:
- choose
Snippet when the canvas is mostly meant to be embedded by another canvas rather than used as a page destination
What it means:
- a widget canvas is a reusable block meant to participate in the widget system
Typical use cases:
- dashboard blocks
- reusable side panels
- role-specific summary panels
- compact reusable information tiles
How it behaves in the platform:
- it appears in the
Widget tab of canvas administration
- it is the only role with explicit role-based availability handling through
available_to_roles
- the widget manager loads widget-role canvases and filters them according to the current user's roles
Why this role is special:
- unlike the other canvas roles,
Widget is not only semantic
- it has a real discovery and availability path in the code
Design guidance:
- choose
Widget when the canvas should behave like a reusable shared block with audience-specific visibility
What it means:
- a property canvas is intended for property-oriented usage rather than page-level or dashboard-level composition
Typical use cases:
- replicator item templates
- specialized field-rendering wrappers
- property-centric entry layouts
How it behaves in the platform:
- it appears in the
Property tab of canvas administration
- it does not currently have a dedicated global runtime permission layer like widgets do
- it functions mainly as a strong organizational and implementation convention
Important integration example:
- replicator properties can reference a canvas to render custom repeated-entry layouts
Design guidance:
- choose
Property when the canvas is primarily a field-level helper or rendering template rather than a screen or widget
Use this rule of thumb:
- choose
Main for full destinations
- choose
Snippet for reusable nested fragments
- choose
Widget for reusable role-targeted dashboard blocks
- choose
Property for field-oriented or property-bound templates
If you are unsure between Main and Snippet, ask:
- will people navigate to this canvas directly, or is it mostly meant to be embedded?
If you are unsure between Snippet and Widget, ask:
- does it need widget discovery and role-based widget availability, or is it just a reusable nested canvas?
The builder exposes a dedicated meta dialog with four practical configuration areas.
What it is:
- an automation that runs before the canvas item tree is rendered
How to configure it:
- open CanvasBuilder
- open the meta dialog
- choose an automation in
Automation on pre-load
Why it matters:
- the canvas calls this automation before rendering its item HTML
- preload logic can prepare canvas variables, compute runtime state, or perform setup work that later items depend on
Use it when:
- items need prepared data
- the canvas should set variables before rendering
- the canvas depends on precomputed context that is not already in the wrapper object or request
Be careful:
- preload automation runs every time the canvas renders
- keep it purposeful and predictable
What it is:
- raw meta/header markup associated with the canvas
How to configure it:
- open the meta dialog
- enter the desired meta tag markup in the
Meta tags editor
Why it matters:
- object and module pages that render canvases may append the canvas meta tags into the response headers area
Use it when:
- the canvas needs page metadata, SEO hints, social metadata, or other head-level additions
What it is:
- canvas-level CSS added during rendering
How to configure it:
- open the meta dialog
- enter CSS in the
CSS editor
Why it matters:
- the canvas renderer injects this CSS into the output
- it lets a canvas carry its own styling when necessary
Use it when:
- the canvas truly needs experience-specific styling that is local to this composition
Be careful:
- keep CSS scoped and deliberate
- avoid turning canvas-level CSS into an ungoverned global styling layer
What it is:
- canvas-level script markup added during rendering
How to configure it:
- open the meta dialog
- enter the script content in the
Scripts editor
Why it matters:
- scripts are added either inline in modal contexts or appended as custom blocks in normal page rendering
Use it when:
- a canvas needs experience-specific client behavior that cannot be achieved through normal configuration alone
Be careful:
- scripts increase complexity and maintenance cost
- prefer structured canvas items and platform capabilities before reaching for custom scripts
¶ Draft And Publish Workflow
CanvasBuilder uses a draft-first workflow.
How it works:
- builder edits store the current item tree into
content_draft
draft_saved is set- the published
content remains unchanged until you publish
Publish copies the draft into content and clears the draft flagDiscard draft removes the draft and restores the builder to the published content
Why it matters:
- canvases can be edited safely without immediately changing the live experience
- this is especially useful for heavily used module pages, widgets, or property templates
Several canvas behaviors are important for implementers even though they are not obvious from the top-level form.
When a canvas renders, Jetstack:
- sets up the focus template holder
- runs preload automation if configured
- renders the main item tree
This means preload automation is the right place to prepare canvas variables or runtime state for later items.
The platform does not store canvas layout as free HTML. It stores a serialized tree of BaseCanvasItem instances and renders each item in order.
This is why:
- CanvasBuilder is the normal authoring surface
- copy, reorder, hide, and nested placement work structurally
When the platform lists widget-role canvases for the current user, it filters them by the user's roles unless the user is a superuser.
This is why available_to_roles matters specifically for widget canvases.
¶ Module Landing Page
Configure:
role = Main- preload automation only if the page needs prepared variables
- compose with view items, widget-like snippets, and object-aware sections
Use it for:
- dashboards
- business landing pages
- high-context module homepages
Configure:
role = Snippet- build a small, focused item tree
- embed it through the canvas item inside larger canvases
Use it for:
- reusable summary blocks
- repeated header or footer compositions
- shared information panels
Configure:
role = Widget- set
available_to_roles
- keep the item tree compact and purpose-built
Use it for:
- manager-only KPIs
- operator action blocks
- personalized summary widgets
Configure:
role = Property- design the layout with replicator or field-oriented usage in mind
Use it for:
- custom replicator row rendering
- property-centered repeated input templates
- Is this really a composition problem, or would a standard view solve it more cleanly?
- Is the canvas a destination, a reusable fragment, a widget, or a property helper?
- Does it need preload automation, or can items work from existing context?
- Will this canvas be reused enough to justify separating it into a snippet or widget?
- Does this canvas need scoped CSS or scripts, or is that a sign the composition should be simplified?
- Use
Widget only when widget discovery and role-based widget availability are actually needed.
- Use
Snippet for reusable nested fragments even though the runtime does not hard-enforce it.
- Treat
Property canvases as field-level helpers and keep them tightly focused.
- Keep preload automation small and purposeful.
- Prefer CanvasBuilder and the meta dialog over manual edits to
content, content_draft, or meta.
- Keep CSS and scripts local, minimal, and well justified.
- Name canvases by job and usage context, not only by visual style.