Image

Responsive image component with Bootstrap utilities.

Basic Usage

from faststrap import Image

# Responsive image
Image(src="/photos/landscape.jpg", alt="Beautiful landscape", fluid=True)

# Thumbnail
Image(src="/profile.jpg", alt="Profile", thumbnail=True)

# Circular
Image(src="/avatar.jpg", alt="Avatar", rounded_circle=True)

API Reference

Parameter	Type	Default	Description
`src`	str	Required	Image source URL
`alt`	`str \\| None`	`None`	Alternative text.
`fluid`	`bool \\| None`	`False`	Add `.img-fluid` for responsive sizing.
`thumbnail`	`bool \\| None`	`False`	Add thumbnail border/padding.
`rounded`	`bool \\| None`	`False`	Round corners.
`rounded_circle`	`bool \\| None`	`False`	Make image circular with `.rounded-circle`.
`align`	`str \\| None`	`None`	Alignment: `"start"`, `"center"`, or `"end"`.
`width`	`str \\| int \\| None`	`None`	Image width. Integers are emitted as pixel values.
`height`	`str \\| int \\| None`	`None`	Image height. Integers are emitted as pixel values.
`loading`	`"lazy" \\| "eager" \\| None`	`None`	Native browser image loading hint.
`**kwargs`	Any	-	Additional HTML attributes

Examples

Responsive Fluid Image

Image(
    src="/hero-image.jpg",
    alt="Hero banner",
    fluid=True
)

Profile Avatar

Image(
    src="/users/john.jpg",
    alt="John Doe",
    rounded_circle=True,
    style={"width": "100px", "height": "100px"}
)

Thumbnail Gallery

Row(
    Col(Image(src="/gallery/1.jpg", thumbnail=True), md=3),
    Col(Image(src="/gallery/2.jpg", thumbnail=True), md=3),
    Col(Image(src="/gallery/3.jpg", thumbnail=True), md=3),
    Col(Image(src="/gallery/4.jpg", thumbnail=True), md=3)
)

Centered Image

Image(
    src="/logo.png",
    alt="Company Logo",
    align="center"
)

Accessibility

Always provide meaningful alt text
Use empty alt="" for decorative images
Ensure sufficient color contrast for overlaid text

API Reference

`faststrap.components.display.image.Image(src, alt=None, fluid=UNSET, thumbnail=UNSET, rounded=UNSET, rounded_circle=UNSET, align=UNSET, width=None, height=None, loading=UNSET, **kwargs)`

Bootstrap Image component with responsive utilities.

Parameters:

Name	Type	Description	Default
`src`	`str`	Image source URL (required)	required
`alt`	`str \| None`	Alternative text for accessibility	`None`
`fluid`	`bool \| None`	Make image responsive (max-width: 100%, height: auto)	`UNSET`
`thumbnail`	`bool \| None`	Add thumbnail styling (border, padding, rounded)	`UNSET`
`rounded`	`bool \| None`	Add rounded corners	`UNSET`
`rounded_circle`	`bool \| None`	Make image circular	`UNSET`
`align`	`AlignType \| None`	Float alignment (start=left, end=right, center)	`UNSET`
`width`	`str \| int \| None`	Image width (CSS value or pixels)	`None`
`height`	`str \| int \| None`	Image height (CSS value or pixels)	`None`
`loading`	`Literal['lazy', 'eager'] \| None`	Native lazy loading (lazy or eager)	`UNSET`
`**kwargs`	`Any`	Additional HTML attributes (cls, id, style, etc.)	`{}`

Returns:

Type	Description
`Img`	FastHTML Img element with Bootstrap image classes

Examples:

Basic responsive image:

>>> Image(src="photo.jpg", alt="Photo", fluid=True)

Thumbnail with rounded corners:

>>> Image(src="avatar.jpg", alt="Avatar", thumbnail=True, rounded_circle=True)

Aligned image:

>>> Image(src="logo.png", alt="Logo", align="center")

Lazy loading:

>>> Image(src="large.jpg", alt="Large image", fluid=True, loading="lazy")

See Also

Bootstrap docs: https://getbootstrap.com/docs/5.3/content/images/

Source code in src/faststrap/components/display/image.py

@register(category="display")
def Image(
    src: str,
    alt: str | None = None,
    fluid: bool | None = UNSET,
    thumbnail: bool | None = UNSET,
    rounded: bool | None = UNSET,
    rounded_circle: bool | None = UNSET,
    align: AlignType | None = UNSET,
    width: str | int | None = None,
    height: str | int | None = None,
    loading: Literal["lazy", "eager"] | None = UNSET,
    **kwargs: Any,
) -> Img:
    """Bootstrap Image component with responsive utilities.

    Args:
        src: Image source URL (required)
        alt: Alternative text for accessibility
        fluid: Make image responsive (max-width: 100%, height: auto)
        thumbnail: Add thumbnail styling (border, padding, rounded)
        rounded: Add rounded corners
        rounded_circle: Make image circular
        align: Float alignment (start=left, end=right, center)
        width: Image width (CSS value or pixels)
        height: Image height (CSS value or pixels)
        loading: Native lazy loading (lazy or eager)
        **kwargs: Additional HTML attributes (cls, id, style, etc.)

    Returns:
        FastHTML Img element with Bootstrap image classes

    Examples:
        Basic responsive image:
        >>> Image(src="photo.jpg", alt="Photo", fluid=True)

        Thumbnail with rounded corners:
        >>> Image(src="avatar.jpg", alt="Avatar", thumbnail=True, rounded_circle=True)

        Aligned image:
        >>> Image(src="logo.png", alt="Logo", align="center")

        Lazy loading:
        >>> Image(src="large.jpg", alt="Large image", fluid=True, loading="lazy")

    See Also:
        Bootstrap docs: https://getbootstrap.com/docs/5.3/content/images/
    """
    # Resolve defaults
    cfg = resolve_defaults(
        "Image",
        fluid=fluid,
        thumbnail=thumbnail,
        rounded=rounded,
        rounded_circle=rounded_circle,
        align=align,
        loading=loading,
    )

    c_fluid = cfg.get("fluid", False)
    c_thumbnail = cfg.get("thumbnail", False)
    c_rounded = cfg.get("rounded", False)
    c_rounded_circle = cfg.get("rounded_circle", False)
    c_align = cfg.get("align")
    c_loading = cfg.get("loading")

    # Build classes
    classes = []

    if c_fluid:
        classes.append("img-fluid")

    if c_thumbnail:
        classes.append("img-thumbnail")

    if c_rounded:
        classes.append("rounded")

    if c_rounded_circle:
        classes.append("rounded-circle")

    # Alignment (float classes)
    if c_align:
        if c_align == "start":
            classes.append("float-start")
        elif c_align == "end":
            classes.append("float-end")
        elif c_align == "center":
            # Center requires mx-auto and d-block
            classes.extend(["d-block", "mx-auto"])

    # Merge with user classes
    user_cls = kwargs.pop("cls", "")
    all_classes = merge_classes(" ".join(classes), user_cls)

    # Build attributes
    attrs: dict[str, Any] = {
        "src": src,
        "cls": all_classes,
    }

    # Alt text (important for accessibility)
    if alt:
        attrs["alt"] = alt

    # Dimensions
    if width:
        attrs["width"] = width if isinstance(width, str) else f"{width}px"
    if height:
        attrs["height"] = height if isinstance(height, str) else f"{height}px"

    # Lazy loading
    if c_loading:
        attrs["loading"] = c_loading

    # Convert remaining kwargs
    attrs.update(convert_attrs(kwargs))

    return Img(**attrs)