---
title: "Element <image>"
source: https://dev.pageseeder.com/psml/elements/element-image.html
description: "PSML Element reference for <image> with attributes: alt, height, src, width"
last_updated: 2026-08-07T17:09:54+10:00
tokens: ~1485
---

# \<image\>

## Summary

The `<image>` element provides a placeholder for displaying an image.

The actual image to display must be a file which media type is of that “image”, that is, starting with `image/`.

In PageSeeder, the image file **must be a PageSeeder document** and the `<image>` element also expresses a relationship between the PSML document and the referenced image file enabling two-way tracking of both files. In effect, an image is similar to a [transclusion](../../reference/glossary/transclusion.md) of an image document.

> **Note:** Requires at least one of the following attributes: `@src, @docid, @uriid.`

## Usage context

| Element category |  |
| --- | --- |
| PSML level | portable |
| Permitted content | none (empty element) |
| Permitted parent |  |
| HTML equivalent | `<img``>` |
| OpenXML equivalent |  |

## Attributes

This element includes the following attributes:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| alt | [xs:string](../datatypes/xml_schema_datatypes.md) | no | Alternative description for non-visual readers |
| archived | [boolean](../datatypes/pageseeder_datatypes.md) | no | Whether the image is archived |
| docid | [document-id](../datatypes/pageseeder_datatypes.md) | no | Document ID of the referenced image, if any |
| height | [xs:positiveInteger](../datatypes/xml_schema_datatypes.md) | no | Height in pixels |
| labels | [label-list](../datatypes/pageseeder_datatypes.md) | no | Comma separated list of image labels |
| src | `xs:string` | no | Path for image |
| unresolved | [boolean](../datatypes/pageseeder_datatypes.md) | no | A boolean to flag images which reference could not be resolved |
| uriid | [xs:long](../datatypes/xml_schema_datatypes.md) | no | The URI ID of the image being referenced |
| width | `xs:positiveInteger` | no | Width in pixels |

The `@unresolved` and `@archived` attributes are [informational](../universal_format/psml_upload.md) and ignored by upload.

### `@alt`

Alternative description for non-visual readers.

### `@archived`

A boolean flag indicating whether the image is archived. *INFORMATIONAL - ignored by upload.*

*This attribute was introduced in PSML v1.3 in PageSeeder 5.99.*

### `@docid`

If the referenced image has a [document id](../../reference/glossary/document_id_docid.md), it is included.

It overrides the @*uriid* on upload.

### `@height`

The height of the image in pixels. If this attribute is omitted, the image is rendered using the default behavior of the layout engine.

### `@labels`

A comma separated list of image labels.

*This attribute was introduced in PSML v1.3 in PageSeeder 5.99.*

### `@src`

The path for the image in PageSeeder. This path can be as follows:

- Relative (for example, `images/mypic.png or ../common/anotherpic.jpg`)
- Absolute (for example, `/ps/myproject/mygroup/images/diagram.png`)
- Permalink (for example, `/ps/uri/123.png`)

It overrides the `@docid` and `@uriid` on upload.

To create permalinks, the path refers to the [URI ID](../../reference/glossary/uri_id.md) of the image (`/ps/uri/[uri id].[extension]`).

To provide a clue to external applications about the media type of the image, you can add an extension after the URI ID in the path. For example, Microsoft Office requires that the path to images include an extension to display them.

> **Note:** On export, the image `@src` is always relative.

> **Warning:** An image `@src` must not point to an external location, so it cannot start with either “`http://`” or “`https://`”. It must always be URL encoded unless `document/@level="processed"`.

### `@unresolved`

If `true`, the target document doesn't exist. *INFORMATIONAL - ignored by upload.*

### `@uriid`

The URI ID of the image being referenced.

*Ignored if uploading to different PageSeeder server.*

### `@width`

The width in pixels. If this attribute is omitted, the image is rendered using the default behavior of the layout engine.

## Examples

###  Image with permalink

Image using a permalink:

```lang-xml

<image src="/ps/uri/23.png" uriid="23" alt="Example"/>
```

> **Note:** When an image uses a permalink, the URI ID must match the ID in the `@src` attribute. 

### Image with path

Image using a PageSeeder path instead of a permalink. In PageSeeder, the URI ID is used to determine what the actual image is. PageSeeder ensures that the path corresponds to the path of the image.

```lang-xml

<image src="/ps/doc/examples/images/sample.jpg"
       uriid="186034" 
       width="600"
       height="400"
       alt="A sample image"/>
```

## Schema

### XML Schema

```lang-xml

<xs:element name="image">
  <xs:complexType>
    <xs:attribute name="archived" type="xs:boolean"/>
    <xs:attribute name="src" type="xs:string" use="required"/>
    <xs:attribute name="width" type="xs:positiveInteger"/>
    <xs:attribute name="height" type="xs:positiveInteger"/>
    <xs:attribute name="alt" type="xs:string"/>
    <xs:attribute name="uriid" type="xs:long"/>
  </xs:complexType>
</xs:element>
```

### Relax Schema

```lang-relax

element image {
   attribute archived { xs:boolean }?,
   attribute src { text},
   attribute uriid { xs:long }?,
   attribute width { xs:positiveInteger }?,
   attribute height { xs:positiveInteger }?,
   attribute alt { text }?,
   empty
}
```

## Compatibility

This element was introduced in the first draft of PSML and is well-supported from PageSeeder 5.1.

Up to PageSeeder 5.7,  much like HTML, `<image>` is a declarative element, in other words, it defines a placeholder for the image referenced by a URL to be displayed. 

From PageSeeder 5.8, the `<image>` element also expresses a relationship between an image file and the PSML document that contains it. Like other type of two-way cross-references, it is possible to track the use of images and ensure that the `<image>` element references an actual image.

From PageSeeder 5.99, images can have their own labels.