Democr.ai Plugin Developer Docs

Breadcrumb

Previous Next

<- Back to Content Components

Definition

Breadcrumb renders hierarchical route or location context as a sequence of segments.

Scope

Use Breadcrumb when the user needs to understand where the current view sits inside a hierarchy. It is content/navigation context, not a layout container.

Segments with a path are clickable unless they are marked as current. Clicking a non-current segment dispatches navigation to that path.

Breadcrumb example

Properties

Property Type Default Notes
segments list[dict] [] Ordered breadcrumb segments. Supports binding and direct updates.
separator string "/" Text separator between segments.
style string client default Standard style property.

Each segment can include:

Field Type Notes
label string | binding Display text.
path string | binding Navigation target for non-current segments.
current bool | binding Marks the current segment. The last segment is treated as current when omitted.

Static Segments

breadcrumb = sdk.ui.Breadcrumb(
    "page_breadcrumb",
    segments=[
        {"label": "Components", "path": "/components"},
        {"label": "Content", "current": True},
    ],
    separator="/",
)
builder.add(breadcrumb)

Store Binding

Bind segments when the breadcrumb trail is driven by page or global store state.

default_segments = [
    {"label": "Components", "path": "/components"},
    {"label": "Content", "current": True},
]
builder.set_store("/components_test/breadcrumb/segments", default_segments, scope="page")

breadcrumb = sdk.ui.Breadcrumb(
    "page_breadcrumb",
    segments=bound.store(
        "/components_test/breadcrumb/segments",
        scope="page",
        default=default_segments,
    ),
)
builder.add(breadcrumb)

Data Model Binding

Use data-model binding when the breadcrumb trail belongs to the current surface data.

default_segments = [
    {"label": "Components", "path": "/components"},
    {"label": "Content", "current": True},
]
builder.set_data("/components_test/breadcrumb_model/segments", default_segments)

breadcrumb = sdk.ui.Breadcrumb(
    "page_breadcrumb",
    segments=bound.data(
        "/components_test/breadcrumb_model/segments",
        default=default_segments,
    ),
)
builder.add(breadcrumb)

Property Updates

Declare capabilities before replacing segments directly.

breadcrumb = sdk.ui.Breadcrumb("page_breadcrumb", segments=[
    {"label": "Components", "path": "/components"},
    {"label": "Content", "current": True},
])
breadcrumb.allow("segments.set")
builder.add(breadcrumb)

The action can update store, data model, and the live breadcrumb:

surface_id = ctx["_surface_id"]
segments = [
    {"label": "Components", "path": "/components"},
    {"label": "Content", "path": "/components/content"},
    {"label": "Breadcrumb", "current": True},
]

return sdk.effects.respond(
    sdk.effects.ui_messages([
        {"stateUpdate": {"scope": "page", "values": {"/components_test/breadcrumb/segments": segments}}},
        sdk.ui.Builder.build_data_model_update_payload(
            surface_id=surface_id,
            data={"components_test": {"breadcrumb_model": {"segments": segments}}},
        ),
    ]),
    sdk.effects.ui_property_update(
        "page_breadcrumb",
        "segments",
        segments,
        surface_id=surface_id,
    ),
)

Visibility And Permissions

show_if, hide_if, and required_permissions are available on Breadcrumb.

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

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

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

Notes

  • The last segment is rendered as current when no segment has current: true.
  • Use path only on segments that should navigate.
  • Segment labels and paths can be literal values or resolved bindings.
Audio Image