# Image Tag

The `image` tag allows you to embed images into your content with various customization options.

## Syntax and usage

Use the `image` tag to include images.
Customize with attributes like `src`, `alt`, `width`, and `height`.

```md
{% img
  alt="Image with custom class"
  srcSet="./images/img-markdoc/image-example-light.png light, ./images/img-markdoc/image-example-dark.png dark"
  className="custom-image-class"
/%}
```

## Attributes

| Attribute | Type | Description |
|  --- | --- | --- |
| src | string | **CONDITIONALLY REQUIRED.**
An `img` tag must contain either an `src`, `srcSet`, or `images` option.
Mutually exclusive with `srcSet` and `images`.
Relative or absolute path to the image in your project, or URL of the image.
Supported file formats: JPEG, PNG, GIF, WebP, SVG, and data URLs. |
| srcSet | string | **CONDITIONALLY REQUIRED.**
An `img` tag must contain either an `src`, `srcSet`, or `images` option.
Mutually exclusive with `src` and `images`.
A set of paths to images in your project, or URLs of images to use for different color modes.
Supported file formats: JPEG, PNG, GIF, WebP, SVG, and data URLs. |
| images | [string] | **CONDITIONALLY REQUIRED.**
An `img` tag must contain either an `src`, `srcSet`, or `images` option.
Mutually exclusive with `src` and `srcSet`.
A list of paths to images in your project, or URLs of images, rendered as a thumbnail gallery in a single row.
Supported file formats: JPEG, PNG, GIF, WebP, SVG, and data URLs.
Supports a maximum of 3 items. |
| alt | string | Descriptive text that provides context for the image to help with accessibility and people with visual impairments or who use assistive technologies to understand the content of images. |
| caption | string | Adds a caption displayed directly below the image, center-aligned. |
| framed | boolean | Wraps the image in a bordered container with rounded corners.
Default: `false`. |
| className | string | CSS class to apply to the image. |
| width | string | number | Sets the width of the image. Accepts:- Numbers (treated as pixels, for example, width=300 → "300px")
- String values with units (for example, "100%", "300px", "20rem", "50vw")

 |
| height | string | number | Sets the height of the image. Accepts:- Numbers (treated as pixels, for example, height=300 → "300px")
- String values with units (for example, "100%", "300px", "20rem", "50vw")

 |
| withLightbox | boolean | Opens the image in a lightbox when the image is clicked.
The lightbox image is opened in its original size or is scaled down to fit the screen if its original size is larger than then screen size.
Default: `false`. |
| lightboxStyle | object | string | Inline styles to apply to the image lightbox.
Accepts either a CSS string or an object with camelCase properties:- As an object: {"backgroundColor": "red", "opacity": "0.5"}
- As a string: "background-color: red; opacity: 0.5"
Common properties include:
- background-color: Control lightbox background color
- opacity: Control lightbox transparency

 |
| align | string | Describes how you want the image aligned on the page.
Options: left, right, center, justify, initial, or inherit.
Default value: left |
| border
 | string
 | Sets the border style of the image. Accepts standard CSS border values, such as:
- "1px solid black" - thin black border
- "2px dashed #FF0000" - dashed red border
- "3px double gray" - double-line gray border

Border styles can also be applied using the style attribute.
 |
| style | object | string | Inline styles to apply to the image.
Accepts either a CSS string or an object with camelCase properties:- As an object: {"marginTop": "20px", "boxShadow": "0 4px 8px rgba(0,0,0,0.1)"}
- As a string: "margin-top: 20px; box-shadow: 0 4px 8px rgba(0,0,0,0.1)"
Common properties include:
- margin, padding: Control spacing around the image
- boxShadow: Add shadow effects
- opacity: Control image transparency
- borderRadius: Round the corners
- filter: Apply visual effects (blur, brightness, etc.)

 |


## Examples

### Basic image with alt text

```md
{% img
  alt="Basic example image"
  srcSet="./images/img-markdoc/image-example-light.png light, ./images/img-markdoc/image-example-dark.png dark"
/%}
```

### Image with width and height

```md
{% img
  alt="Image with dimensions"
  srcSet="./images/img-markdoc/image-example-light.png light, ./images/img-markdoc/image-example-dark.png dark"
  width=300
  height=200
/%}
```

### Image with alignment

```md
{% img
  alt="Center aligned image"
  width=200
  height=200
  srcSet="./images/img-markdoc/image-example-light.png light, ./images/img-markdoc/image-example-dark.png dark"
  align="right"
/%}
```

### Image with border

```md
{% img
  alt="Image with border"
  srcSet="./images/img-markdoc/image-example-light.png light, ./images/img-markdoc/image-example-dark.png dark"
  border="10px solid red"
/%}
```

### Image with custom styles

```md
{% img
  alt="Styled image"
  srcSet="./images/img-markdoc/image-example-light.png light, ./images/img-markdoc/image-example-dark.png dark"
  style={"border": "10px solid red", "borderRadius": "50px", "cursor": "pointer"}
/%}
```

### Image with srcSet for different color modes

```md
{% img
  alt="Color mode aware image"
  width=200
  height=200
  srcSet="./images/img-markdoc/image-example-light.png light, ./images/img-markdoc/image-example-dark.png dark"
/%}
```

### Image with className

```md
{% img
  alt="Image with custom class"
  srcSet="./images/img-markdoc/image-example-light.png light, ./images/img-markdoc/image-example-dark.png dark"
  className="custom-image-class"
/%}
```

### Thumbnail gallery with caption

```md
{% img
  alt="Gallery containing three images: one with Markdoc logo, one with OpenAPI logo, one with Arazzo logo"
  images=["./images/img-markdoc/markdoc.svg", "./images/img-markdoc/openapi.svg", "./images/img-markdoc/arazzo.svg"]
  caption="Check out our resources in the Learn section!"
/%}
```

## Best practices

**Write meaningful alt text**

Always include descriptive alt text that conveys the purpose and content of the image.
Descriptive alt text improves accessibility and helps users understand the image's context when it fails to load or if users have visual impairments or use assistive technologies to understand the content of images.

**Use images purposefully**

Only include images that add value to your content.
Avoid decorative images that don't contribute to understanding the subject matter.

**Maintain responsive design**

Set appropriate width and height attributes to prevent layout shifts and to prevent pixelation.
Also, consider how images display across different screen sizes.

**Enhance visual hierarchy**

Use alignment to create visual flow and balance.
Apply consistent styling (borders, shadows, etc.) across similar image types.

## Resources

- **[Markdoc overview for technical writers](https://redocly.com/learn/markdoc)** - Learn how to use Markdoc in your documentation
- **[Markdoc tags](/docs/realm/content/markdoc-tags)** - See the full list of supported Markdoc tags