Skip to content

Structured Display

KeyValueList, RecordDetail, CodeBlock, and JsonViewer are small data/dev-app primitives for admin panels, AI tools, and internal dashboards.

Quick Start

from faststrap import CodeBlock, JsonViewer, KeyValueList, RecordDetail

KeyValueList({
    "Status": "Ready",
    "Owner": "Ops",
})

RecordDetail(
    {"ID": 42, "State": "queued"},
    title="Training Job",
    subtitle="Submitted 2 minutes ago",
)

CodeBlock("print('hello')", language="python", filename="demo.py")
JsonViewer({"accuracy": 0.94, "loss": 0.12}, title="Metrics")

Usage Scenarios

Admin Record Detail

RecordDetail(
    {
        "Name": "Acme Corp",
        "Plan": "Enterprise",
        "Seats": "25",
        "Status": "Active",
    },
    title="Acme Corp",
    subtitle="Customer since 2023",
    actions=[
        Button("Edit", variant="primary", href=f"/customers/{id}/edit"),
        Button("Deactivate", variant="danger"),
    ],
)

API Response Viewer

JsonViewer(
    response_json,
    title="API Response",
    expanded=False,
)

Code Snippet with Copy

CodeBlock(
    "from faststrap import Button\nButton('Click me')",
    language="python",
    filename="main.py",
    copy=True,
)

Key-Value List in a Card

Card(
    Card.Header("System Status"),
    Card.Body(
        KeyValueList({
            "CPU": "42%",
            "Memory": "6.2 GB",
            "Disk": "120 GB free",
        }, striped=True),
    ),
)

Notes

  • CodeBlock does not ship a syntax highlighter in core. It emits language-* classes so an optional highlighter can enhance it later.
  • JsonViewer(title=...) uses a native <details> element; omit title for an always-visible block.
  • These components are core-safe: no JavaScript and no extra dependencies.

Accessibility

  • CodeBlock uses semantic <pre> and <code> markup.
  • JsonViewer uses native <details>/<summary> for expand/collapse.
  • Ensure CodeBlock text meets contrast requirements for your theme.

Parameters

Component Key Parameters Notes
KeyValueList items, striped, compact Accepts a dict, tuple list, or label/value mappings.
RecordDetail items, title, subtitle, actions Card-style detail view around KeyValueList.
CodeBlock code, language, filename, copy, wrap Escapes code content by default. copy=True shows a visual badge only.
JsonViewer data, title, expanded Pretty-prints JSON-like data using json.dumps(..., default=str).

API Reference

faststrap.components.display.structured.KeyValueList(items, *, striped=False, compact=False, **kwargs)

Render label/value metadata rows.

Source code in src/faststrap/components/display/structured.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
@register(category="display")
@beta
def KeyValueList(
    items: KeyValueItems,
    *,
    striped: bool = False,
    compact: bool = False,
    **kwargs: Any,
) -> Div:
    """Render label/value metadata rows."""
    user_cls = kwargs.pop("cls", "")
    row_cls = "py-1" if compact else "py-2"
    rows = []
    for index, (label, value) in enumerate(_normalize_items(items)):
        rows.append(
            Div(
                Div(label, cls="fw-semibold text-muted"),
                Div(value, cls="text-body"),
                cls=merge_classes(
                    "d-grid gap-1 gap-sm-3 border-bottom",
                    row_cls,
                    "bg-body-tertiary px-2" if striped and index % 2 else "",
                ),
                style="grid-template-columns: minmax(9rem, 0.35fr) 1fr;",
            )
        )

    attrs: dict[str, Any] = {"cls": merge_classes("faststrap-key-value-list", user_cls)}
    attrs.update(convert_attrs(kwargs))
    return Div(*rows, **attrs)

faststrap.components.display.structured.RecordDetail(items, *, title=None, subtitle=None, actions=None, **kwargs)

Render a card-style detail view for one record.

Source code in src/faststrap/components/display/structured.py 
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
@register(category="display")
@beta
def RecordDetail(
    items: KeyValueItems,
    *,
    title: str | None = None,
    subtitle: str | None = None,
    actions: Any | list[Any] | tuple[Any, ...] | None = None,
    **kwargs: Any,
) -> Div:
    """Render a card-style detail view for one record."""
    user_cls = kwargs.pop("cls", "")

    header_children: list[Any] = []
    if title:
        header_children.append(H3(title, cls="h5 mb-1"))
    if subtitle:
        header_children.append(P(subtitle, cls="text-muted mb-0"))

    header: Any | None = None
    if header_children or actions is not None:
        action_children: list[Any] = []
        if actions is not None:
            action_children = list(actions) if isinstance(actions, (list, tuple)) else [actions]
        header = Div(
            Div(*header_children),
            Div(*action_children, cls="d-flex flex-wrap gap-2") if action_children else "",
            cls="d-flex flex-column flex-sm-row justify-content-between gap-3",
        )

    attrs: dict[str, Any] = {"cls": merge_classes("faststrap-record-detail", user_cls)}
    attrs.update(convert_attrs(kwargs))
    return Card(KeyValueList(items), header=header, **attrs)

faststrap.components.display.structured.CodeBlock(code, *, language=None, filename=None, copy=False, wrap=False, **kwargs)

Render escaped source code in a Bootstrap-styled block.

Source code in src/faststrap/components/display/structured.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
@register(category="display")
@beta
def CodeBlock(
    code: str,
    *,
    language: str | None = None,
    filename: str | None = None,
    copy: bool = False,
    wrap: bool = False,
    **kwargs: Any,
) -> Div:
    """Render escaped source code in a Bootstrap-styled block."""
    user_cls = kwargs.pop("cls", "")
    code_cls = f"language-{language}" if language else ""

    header = None
    if filename or copy:
        header = Div(
            Span(filename or "Code", cls="fw-semibold small text-muted"),
            Span("Copy", cls="badge text-bg-secondary") if copy else "",
            cls="d-flex align-items-center justify-content-between border-bottom px-3 py-2",
        )

    pre_cls = merge_classes("mb-0 p-3", "text-wrap" if wrap else "overflow-auto")
    attrs: dict[str, Any] = {
        "cls": merge_classes("faststrap-code-block border rounded bg-body-tertiary", user_cls)
    }
    attrs.update(convert_attrs(kwargs))
    return Div(header or "", Pre(Code(code, cls=code_cls), cls=pre_cls), **attrs)

faststrap.components.display.structured.JsonViewer(data, *, title=None, expanded=True, **kwargs)

Render JSON-like data as an escaped, readable details block.

Source code in src/faststrap/components/display/structured.py 
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
@register(category="display")
@beta
def JsonViewer(
    data: Any,
    *,
    title: str | None = None,
    expanded: bool = True,
    **kwargs: Any,
) -> Any:
    """Render JSON-like data as an escaped, readable details block."""
    rendered = json.dumps(data, indent=2, sort_keys=True, default=str)
    block = CodeBlock(rendered, language="json")
    if title is None:
        user_cls = kwargs.pop("cls", "")
        attrs: dict[str, Any] = {"cls": merge_classes("faststrap-json-viewer", user_cls)}
        attrs.update(convert_attrs(kwargs))
        return Div(block, **attrs)

    user_cls = kwargs.pop("cls", "")
    attrs = {"cls": merge_classes("faststrap-json-viewer", user_cls)}
    if expanded:
        attrs["open"] = True
    attrs.update(convert_attrs(kwargs))
    return ft("details", ft("summary", title, cls="fw-semibold mb-2"), block, **attrs)