Democr.ai Plugin Developer Docs

ContentArea

Previous Next

<- Back to Layout Components

Definition

ContentArea marks the main content region of a structured layout. It is a container for page content beside or below shell elements such as Sidebar, Header, or split panes.

Scope

Use ContentArea for the primary workspace of a page. It is a general container, not a layout-direction primitive. The first child should normally be a layout component with explicit child distribution semantics, such as Column, Row, ScrollArea, or Splitter.

Use Column for vertical stacking inside the workspace, Row for horizontal distribution, and ScrollArea when content can overflow. This keeps the behavior predictable across desktop and web clients.

Properties

Property Type Default Notes
children list[str | Component] [] Content rendered in the main area. Prefer a single explicit layout container as the first child.
stretch bool false Lets the content area fill available space.
style string None Common component style property. Supports direct property updates.

Static ContentArea

body = sdk.ui.Column("content_body", ["main_text"])
builder.add(body)

content = sdk.ui.ContentArea("content_area", [body.id])
content.set_property("stretch", True)
builder.add(content)

First-Level Layout

ContentArea should not be used as the component that decides whether repeated children flow vertically or horizontally. Put a layout container at the first level and update that container when content changes dynamically.

body = sdk.ui.Column("content_body", ["row_1", "row_2"])
body.set_property("stretch", True)
builder.add(body)

content = sdk.ui.ContentArea("content_area", [body.id])
content.set_property("stretch", True)
builder.add(content)

With ScrollArea

Use this pattern when the main content can be taller than the available space.

stack = sdk.ui.Column("content_stack", ["row_1", "row_2"])
builder.add(stack)

scroll = sdk.ui.ScrollArea("content_scroll", [stack.id])
scroll.set_property("stretch", True)
scroll.set_property("scroll_x", False)
builder.add(scroll)

content = sdk.ui.ContentArea("content_area", [scroll.id])
content.set_property("stretch", True)
builder.add(content)

Store Binding

Bind style when the content area state is driven by the page store.

content = sdk.ui.ContentArea("content_area_store", [body.id])
content.set_property("stretch", True)
content.set_property(
    "style",
    bound.store("/components_test/contentarea/style", scope="page", default=""),
)
builder.add(content)

Data Model Binding

Use data-model binding when the content area style comes from the surface data model.

content = sdk.ui.ContentArea("content_area_data", [body.id])
content.set_property("stretch", True)
content.set_property(
    "style",
    bound.data("/components_test/contentarea_model/style", default=""),
)
builder.add(content)

Property Updates

Declare capabilities before updating style directly.

content = sdk.ui.ContentArea("content_area_live", [body.id])
content.set_property("stretch", True)
content.allow("style.set")
builder.add(content)

The action can update store, data model, and live content-area properties:

return sdk.effects.respond(
    sdk.effects.ui_property_update("content_area_live", "style", next_style, surface_id=surface_id),
)

Dynamic Children

When the main workspace changes without replacing the whole page, update the first-level layout container inside ContentArea. Do not append repeated rows directly to ContentArea.children unless the client-specific layout behavior is acceptable for that use case.

body = sdk.ui.Column("content_area_dynamic_body", ["row_1", "row_2"])
body.set_property("stretch", True)
body.allow("children.append", "children.remove")
builder.add(body)

content = sdk.ui.ContentArea("content_area_dynamic", [body.id])
content.set_property("stretch", True)
builder.add(content)

# In the action:
return sdk.effects.respond(
    sdk.effects.ui_collection_append("content_area_dynamic_body", "children", row_component_dict, surface_id=surface_id),
)

Visibility And Permissions

show_if, hide_if, and required_permissions are available on ContentArea.

content.set_show_if({
    "conditions": [
        {"left": bound.store("/components_test/visibility/contentarea_show", scope="page", default=True), "op": "==", "right": True}
    ]
})

content.set_hide_if({
    "conditions": [
        {"left": bound.store("/components_test/visibility/contentarea_hide", scope="page", default=False), "op": "==", "right": True}
    ]
})

content.set_required_permissions(["components.layout.view"])

Notes

  • ContentArea identifies the main workspace; it is not a layout-direction or scrolling primitive.
  • Put a direction-aware layout container as the first child when repeated content must flow predictably.
  • Put ScrollArea inside ContentArea for long content.
  • Use stretch: true when ContentArea must fill the remaining width or height in a shell layout.
  • Keep inner wrappers at min-height: 0 when combining ContentArea with bounded-height layouts and scroll areas.
Container ScrollArea