Skip to content

TextClamp

TextClamp renders long content with optional expandable behavior.

Use it when pages need cleaner previews without overwhelming users.

Import

from faststrap import TextClamp

Basic usage

TextClamp(
    "Very long article preview text ...",
    max_chars=120,
)

Why this is useful

  • Keeps cards/lists visually balanced when text length varies.
  • Improves scanability in feeds, blog indexes, and catalog pages.
  • Gives users control to expand full content only when needed.

Common use cases

  1. Blog/news feed previews.
  2. Product descriptions on cards.
  3. Testimonial excerpts.
  4. Comment/thread summaries.

Without show more button

TextClamp(
    "Very long article preview text ...",
    max_chars=120,
    show_more=False,
)

This is useful for strict preview layouts where expansion is not needed.

Custom button labels and style

TextClamp(
    article_body,
    max_chars=180,
    expand_label="Read full post",
    collapse_label="Show less",
    button_cls="btn btn-sm btn-outline-primary mt-2",
)

Full card example

Card(
    H5(post.title),
    TextClamp(
        post.body,
        max_chars=220,
        expand_label="Read full post",
        collapse_label="Collapse",
        button_cls="btn btn-sm btn-link p-0 mt-2",
    ),
)

Parameters

Parameter Type Default Description
text str required Full text content.
max_chars int 180 Number of characters before truncation. Minimum effective value is 1.
show_more bool True Render expandable full text and toggle button.
expand_label str "Show more" Expand button text.
collapse_label str "Show less" Collapse button text.
button_cls str Bootstrap link button classes Toggle button classes.
ellipsis str "..." Trailing truncation string.
**kwargs Any Extra wrapper attributes.

Notes

  • If text length is below max_chars, no toggle button is rendered.
  • show_more=False keeps preview-only output.

API Reference

faststrap.components.display.text_clamp.TextClamp(text, max_chars=180, show_more=True, expand_label='Show more', collapse_label='Show less', button_cls='btn btn-link p-0 text-decoration-none', ellipsis='...', **kwargs)

Render long text with optional expandable behavior.

Source code in src/faststrap/components/display/text_clamp.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
@register(category="display")
def TextClamp(
    text: str,
    max_chars: int = 180,
    show_more: bool = True,
    expand_label: str = "Show more",
    collapse_label: str = "Show less",
    button_cls: str = "btn btn-link p-0 text-decoration-none",
    ellipsis: str = "...",
    **kwargs: Any,
) -> Div:
    """Render long text with optional expandable behavior."""
    safe_max = max(1, max_chars)
    if len(text) <= safe_max:
        attrs = {"cls": kwargs.pop("cls", "")}
        attrs.update(convert_attrs(kwargs))
        return Div(text, **attrs)

    preview_text = text[:safe_max].rstrip() + ellipsis
    user_cls = kwargs.pop("cls", "")
    attrs = {"cls": merge_classes("fs-text-clamp", user_cls)}
    attrs.update(convert_attrs(kwargs))

    preview = Span(preview_text, data_fs_preview="true")
    if not show_more:
        return Div(preview, data_fs_text_clamp="false", **attrs)

    full = Span(text, cls="d-none", data_fs_full="true")
    toggle_button = Button(
        expand_label,
        type="button",
        cls=button_cls,
        data_fs_text_toggle="true",
        data_fs_expand_label=expand_label,
        data_fs_collapse_label=collapse_label,
        aria_expanded="false",
    )
    return Div(preview, full, toggle_button, data_fs_text_clamp="true", **attrs)