---
title: "Image styles"
manual: "RTE CKEditor Image"
version: "main"
permalink: "https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:examples-image-styles@main"
source: "Examples/Image-Styles.rst"
rendered: "2026-10-01T01:27:51+00:00"
---

# Image styles {#examples-image-styles}

This extension provides **two ways** to apply styles to images in the editor.
Understanding the difference is important for choosing the right approach.

**Table of Contents**

-   [Overview: Two styling approaches](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:overview-two-styling-approaches@main)
-   [Built-in balloon toolbar (recommended)](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:built-in-balloon-toolbar-recommended@main)
-   [Native CKEditor style dropdown (advanced)](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:native-ckeditor-style-dropdown-advanced@main)
-   [Troubleshooting](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:troubleshooting@main)
-   [Choosing the right approach](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:choosing-the-right-approach@main)
-   [Related documentation](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:related-documentation@main)

## Overview: Two styling approaches {#overview-two-styling-approaches}

> [!IMPORTANT]
> There are two separate styling systems:
>
> 1.  **Built-in balloon toolbar** (works out of the box)
> 1.  **Native CKEditor style dropdown** (requires configuration)
>
> Most users should use the **built-in balloon toolbar** which works
> automatically with the `rteWithImages` preset.

## Built-in balloon toolbar (recommended) {#built-in-balloon-toolbar-recommended}

The extension provides **built-in image alignment buttons** that appear in a
balloon toolbar when you click on an image.

**No configuration required** \- works out of the box with the
`rteWithImages` preset.

### Available styles {#available-styles}

| Button | CSS Class | Effect |
| --- | --- | --- |
| Align Left | `image-left` | Float left with text wrap |
| Align Center | `image-center` | Centered block element |
| Align Right | `image-right` | Float right with text wrap |
| Inline | `image-inline` | Inline with text |
| Block | `image-block` | Full-width block element |

### How to use {#how-to-use}

1.  Insert an image using the **Insert Image** button in the toolbar.
1.  **Click on the image** in the editor.
1.  A **balloon toolbar** appears above the image with alignment buttons.
1.  Click an alignment button to apply the style.

> [!NOTE]
> The balloon toolbar appears directly above the selected image with icons
> for alignment (left, center, right) and display mode (inline, block).

### Configuration (default) {#configuration-default}

The balloon toolbar is configured in `rteWithImages.yaml`:

**EXT:rte_ckeditor_image/Configuration/RTE/rteWithImages.yaml**

```yaml
editor:
  config:
    # Load CSS for alignment styles
    contentsCss:
      - 'EXT:rte_ckeditor_image/Resources/Public/Css/image-alignment.css'

    typo3image:
      toolbar:
        - 'editTypo3Image'
        - '|'
        - 'imageStyle:image-left'
        - 'imageStyle:image-center'
        - 'imageStyle:image-right'
        - '|'
        - 'imageStyle:image-inline'
        - 'imageStyle:image-block'
```

### CSS styles {#css-styles}

The extension provides CSS styles in `image-alignment.css`:

**Built-in alignment CSS**

```css
/* Float left with text wrap */
.image-left { float: left; margin: 0 1rem 1rem 0; }

/* Float right with text wrap */
.image-right { float: right; margin: 0 0 1rem 1rem; }

/* Centered block */
.image-center { display: block; margin: 0 auto 1rem; }

/* Inline with text */
.image-inline { display: inline; vertical-align: middle; }

/* Full-width block */
.image-block { display: block; width: 100%; margin: 1rem 0; }
```

> [!TIP]
> Include the CSS in your frontend:
>
> ```typoscript
> page {
>     includeCSS {
>         imageAlignment = EXT:rte_ckeditor_image/Resources/Public/Css/image-alignment.css
>     }
> }
> ```

### Caption width constraint {#caption-width-constraint}

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

Figures with captions are automatically constrained to the image width
via an inline `max-width` style on the `<figure>` element. This
prevents long caption text from expanding the figure beyond the image
boundary.

![Before and after comparison of figcaption width constraint](../Images/caption-width-fix-667.png)

The constraint is applied by the Fluid partial
`Partials/Image/Figure.html`:

**Figure.html — conditional max-width**

```html
<figure class="{figureClasses}{additionalClass}"
        {f:if(condition: image.width,
          then: ' style="max-width: {image.width}px"')}>
```

Long unbreakable words or URLs in captions break via
`overflow-wrap: break-word` in `image-alignment.css`.

## Native CKEditor style dropdown (advanced) {#native-ckeditor-style-dropdown-advanced}

For **custom styles** beyond basic alignment, you can use the native CKEditor
style dropdown. This requires additional configuration.

> [!IMPORTANT]
> The native style dropdown is **separate** from the built-in balloon
> toolbar buttons. Use this approach when you need custom CSS classes
> (e.g., Bootstrap utilities).

### Requirements {#requirements}

1.  Add `style` to your toolbar configuration.
1.  Define style definitions for `img` elements.
1.  Ensure `StyleUtils` and `GeneralHtmlSupport` plugins are loaded
    (automatic).

### Configuration example {#configuration-example}

**EXT:my_site/Configuration/RTE/MyPreset.yaml**

```yaml
imports:
  - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Default.yaml" }

editor:
  config:
    # Add 'style' to the toolbar
    toolbar:
      items:
        - style           # <-- Required for style dropdown
        - heading
        - '|'
        - insertimage
        - link
        - '|'
        - bold
        - italic

    # Define styles for images
    style:
      definitions:
        - name: 'Float Left (Bootstrap)'
          element: 'img'
          classes: ['float-start', 'me-3', 'mb-3']
        - name: 'Float Right (Bootstrap)'
          element: 'img'
          classes: ['float-end', 'ms-3', 'mb-3']
        - name: 'Centered'
          element: 'img'
          classes: ['d-block', 'mx-auto']
        - name: 'Rounded'
          element: 'img'
          classes: ['rounded']
        - name: 'Thumbnail'
          element: 'img'
          classes: ['img-thumbnail']
```

### How to use {#how-to-use-1}

1.  Insert an image.
1.  **Select the image** (click on it).
1.  Open the **Style** dropdown in the main toolbar.
1.  Select a style from the dropdown.

> [!NOTE]
> The style dropdown only shows styles applicable to the selected element.
> Make sure you have the image selected when looking for image styles.

### Style groups {#style-groups}

Organize styles into groups for better UX:

**Grouped style definitions**

```yaml
editor:
  config:
    style:
      definitions:
        - name: 'Float Left'
          element: 'img'
          classes: ['float-start', 'me-3']
        - name: 'Float Right'
          element: 'img'
          classes: ['float-end', 'ms-3']
        - name: 'Thumbnail'
          element: 'img'
          classes: ['img-thumbnail']
        - name: 'Rounded'
          element: 'img'
          classes: ['rounded']

      groupDefinitions:
        - name: 'Image Alignment'
          styles: ['Float Left', 'Float Right']
        - name: 'Image Style'
          styles: ['Thumbnail', 'Rounded']
```

## Troubleshooting {#troubleshooting}

### Style dropdown not appearing {#style-dropdown-not-appearing}

**Symptoms**: No "Styles" dropdown visible in the toolbar.

**Solution**: Add `style` to your toolbar configuration:

```yaml
editor:
  config:
    toolbar:
      items:
        - style    # <-- Add this
        - heading
        - insertimage
        # ...
```

### Styles disabled when image selected {#styles-disabled-when-image-selected}

**Symptoms**: Style dropdown shows options but they're grayed out for images.

**Cause**: Missing dependencies or incorrect style definitions.

**Solution**: Verify your style definitions target `img` elements:

```yaml
style:
  definitions:
    - name: 'My Image Style'
      element: 'img'      # <-- Must be 'img'
      classes: ['my-class']
```

### Balloon toolbar not showing {#balloon-toolbar-not-showing}

**Symptoms**: No toolbar appears when clicking an image.

**Solution**: Ensure you're using the `rteWithImages` preset or have
configured `typo3image.toolbar` in your RTE configuration.

**Check your preset includes the image plugin**

```yaml
imports:
  - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Default.yaml" }
```

## Choosing the right approach {#choosing-the-right-approach}

| Feature | Balloon Toolbar (Built-in) | Style Dropdown (Native) |
| --- | --- | --- |
| Configuration | None required | YAML configuration needed |
| Styles available | 5 style options (3 alignment + 2 display) | Custom (you define them) |
| Location | Balloon above image | Main toolbar dropdown |
| Best for | Basic alignment | Custom Bootstrap/CSS classes |
| CSS included | Yes (image-alignment.css) | No (provide your own) |

**Recommendation**: Start with the built-in balloon toolbar. Only configure
the native style dropdown if you need custom CSS classes beyond the basic
alignments.

## Related documentation {#related-documentation}

-   [CKEditor Style Integration](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:ckeditor-style-integration@main) \- Technical details on StyleUtils
-   [Responsive Images](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:examples-responsive-images@main) \- Responsive image examples
-   [Integration & Configuration](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:integration@main) \- Configuration guide