---
title: "Image and figure floating and alignment"
manual: "How to Document"
version: "main"
permalink: "https://docs.typo3.org/permalink/h2document:image-float-alignment"
source: "Reference/ReStructuredText/Graphics/ImageAlignment.rst"
rendered: "2026-10-01T06:42:43+00:00"
---

# Image and figure floating and alignment {#image-float-alignment}

<!-- TODO: no Markdown rendering for "versionadded" -->

Float and alignment support for images and figures was introduced in
render-guides version 0.37.0.

Images and figures can be floated to the left or right so that surrounding
text wraps around them. This is useful for inline illustrations, icons,
or any image that should be embedded within a text flow rather than
displayed as a standalone block.

## Align option {#image-float-align-option}

Use the `:align:` option to float an image or figure. It works on both
`..  image::` and `..  figure::` directives and supports `left`,
`right`, and `center`. Other classes such as `with-shadow` go
into the `:class:` option next to it:

```rst
..  figure:: /Images/MyImage.png
    :alt: Description of the image
    :align: right
    :class: with-shadow

    Caption text here

Surrounding text will wrap to the left of the image.
```

Using `:align: center` centers the figure without any text wrapping.

The CSS classes `float-start` and `float-end` in `:class:` still
float an image the same way. The Bootstrap 4 class names `float-left` and
`float-right` are deprecated: the renderer rewrites them to
`float-start` and `float-end` and logs a warning.

## Clearing floats {#image-float-clearing}

After a floated image, you may want subsequent content to appear below the
image rather than wrapping around it. Use the `clear-both` class to clear
floats:

```rst
..  figure:: /Images/MyImage.png
    :alt: Description of the image
    :align: left

    Caption

This text wraps around the image.

..  rst-class:: clear-both

This text appears below the image.
```

The `..  rst-class:: clear-both` directive applies the CSS `clear: both`
property to the next element, forcing it below any floated content.

## Responsive behavior {#image-float-responsive}

Floated images automatically switch to full-width block display on small
screens (below 576px). This ensures readable text on mobile devices
without horizontal scrolling.

### Example 8: figure floated left {#image-float-example-8}

![Example figure floated left](../../../_Images/a4.jpg)

Typesetting is the composition of text by means of arranging physical types
or the digital equivalents. Stored letters and other symbols are retrieved
and ordered according to a language's orthography for visual display.
Typesetting requires one or more fonts.

```rst
..  figure:: /_Images/a4.jpg
    :alt: Example figure floated left
    :align: left
    :class: with-shadow
    :width: 150px

    A figure floated to the left

Typesetting is the composition of text by means of arranging
physical types or the digital equivalents. ...

..  rst-class:: clear-both
```

### Example 9: figure aligned right {#image-float-example-9}

![Example figure aligned right](../../../_Images/a4.jpg)

Typesetting is the composition of text by means of arranging physical types
or the digital equivalents. Stored letters and other symbols are retrieved
and ordered according to a language's orthography for visual display.
Typesetting requires one or more fonts.

```rst
..  figure:: /_Images/a4.jpg
    :alt: Example figure aligned right
    :align: right
    :width: 150px

    A figure aligned right via :align:

Typesetting is the composition of text by means of arranging
physical types or the digital equivalents. ...

..  rst-class:: clear-both
```

### Example 10: image floated left with shadow {#image-float-example-10}

![Example image floated left](../../../_Images/a4.jpg)

Typesetting is the composition of text by means of arranging physical types
or the digital equivalents. Stored letters and other symbols are retrieved
and ordered according to a language's orthography for visual display.
Typesetting requires one or more fonts.

```rst
..  image:: /_Images/a4.jpg
    :alt: Example image floated left
    :align: left
    :class: with-shadow
    :width: 150px

Typesetting is the composition of text by means of arranging
physical types or the digital equivalents. ...

..  rst-class:: clear-both
```

## Best practices for floating {#image-float-best-practices}

-   Always use `..  rst-class:: clear-both` after floated content to prevent
    layout issues with subsequent sections
-   Set an explicit `:width:` on floated images to control how much space
    text has to wrap around
-   Floated figures are limited to 50% of the page width to ensure readability
-   Prefer `:align:` for floating; add other classes like `with-shadow`
    with `:class:` next to it
-   Test on narrow viewports to verify the responsive behavior