# Images
Turn image-only paragraphs into styled figures and galleries.
import { Callout, Steps } from '@prosefly/astro-components';
The `proseflyComponents()` integration enables image galleries in Markdown and
MDX so authors can write normal Markdown images while the site renders styled
figures and multi-image galleries.
[Dahlia](https://astro-theme-dahlia.prosefly.dev/) and
[Lotus](https://astro-theme-lotus.prosefly.dev/) already register the
`proseflyComponents()` integration. The transform, styles, and runtime are active
automatically.
## What Authors Write
A paragraph that contains only one image becomes a styled figure.
```mdx
```
A paragraph that contains multiple images becomes a gallery.
```mdx
```
The image strip keeps its horizontal layout and next-image preview. Below it,
the current image's alt text appears on the left, with left/right arrow buttons
on the right. The description follows both arrow navigation and manual
scrolling. Images with empty alt text have no visible description.
Arrows use a disabled color and cannot be clicked when no further scrolling is
possible in that direction.
## Standalone Astro Setup
If you are not using a Prosefly theme, register the shared integration in
`astro.config.ts`. The image transform, CSS, and client runtime are enabled by
default.
```ts title="astro.config.ts"
import { defineConfig } from 'astro/config';
import proseflyComponents from '@prosefly/astro-components/integration';
export default defineConfig({
integrations: [proseflyComponents()],
});
```
The integration adds the `remarkImageGallery` transform for `.md` and `.mdx`
files. It generates gallery HTML while preserving the original image nodes for
Astro's image handling. The integration loads the shared CSS and client runtime;
no layout imports are required.
Multi-image figures use a light-DOM `` custom element. Each
gallery initializes when inserted, including after Astro page transitions, and
releases scroll/button listeners, image-loading listeners, and its resize
observer when removed. Reinserting a gallery preserves its scroll position.
Single images remain ordinary figures, and galleries remain horizontally
scrollable without JavaScript.
To keep the other integration features but disable galleries and their assets,
set `markdown.imageGallery` to `false`.
```ts title="astro.config.ts"
proseflyComponents({
markdown: { imageGallery: false },
})
```
## Use the Component Directly
In an Astro component or MDX page, you can also import `ImageGallery` and
provide image children explicitly. The component owns the same CSS and browser
runtime as automatically generated galleries.
```mdx
import { ImageGallery } from '@prosefly/astro-components';
```
## Visible Overflow
By default, galleries keep overflowing images inside a horizontally scrollable
strip. To let images extend beyond the gallery container, set `overflow` to
`"visible"`:
```mdx
```
Visible overflow keeps the image strip layout and hides the scroll arrows. The
caption shows the first image's alt text. Ancestor elements must also allow
overflow for images to extend beyond them; this mode can make the page wider
than the viewport. Omit the option or use `overflow="auto"` to keep scrolling.
For automatically generated galleries in `.md` and `.mdx` files, configure the
shared integration:
```ts title="astro.config.ts"
proseflyComponents({
markdown: { imageGallery: { overflow: 'visible' } },
})
```
## Authoring Rules
1. **Keep gallery paragraphs image-only.**
Do not add prose, links, inline code, or captions to the same paragraph.
Mixed content stays as normal Markdown.
2. **Use helpful alt text.**
The transform preserves each image element. The `alt` text is still the main
accessibility description for the image, and also appears below multi-image
galleries as the current image's description.
3. **Group images intentionally.**
Put related screenshots in the same paragraph. Add a blank line before the
next paragraph when a new gallery should start.
Dahlia and Lotus already register the shared integration. Do not add another
`proseflyComponents()` instance in theme projects. The integration configures
the gallery transform, CSS, and runtime together.