# Retrieving image dimensions

> Learn how to access an image's width and height in Cascade CMS using the Cascade API (via structured data node or locateFile) or an Index Block with Velocity.

URL: https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/image-dimensions.html
category: Developing in Cascade
article-type: how-to
content-kind: article
release-availability: all
tags: velocity, files
updated: 2026-10-06

Cascade CMS exposes an image's width and height as integer pixel values — useful for setting HTML `width` and `height` attributes (which prevents Cumulative Layout Shift), responsive logic, or dynamic markup. Dimensions are accessible directly via the Cascade API or as child nodes when aggregating assets through an Index Block.

## Using the Cascade API

There are two ways to access dimensions through the API depending on how you're referencing the image.

### Via a structured data node

If your data definition includes a node pointing to an image file, use `$currentPage.getStructuredDataNode()` with the node's path to retrieve it. Because the node wraps the file asset, you need `.asset.dimensions` to reach the dimension values.

```velocity
#set($image = $currentPage.getStructuredDataNode("group/image-node"))
$image.asset.dimensions.width
$image.asset.dimensions.height
```

> **Working inside a loop?**
>
> `$currentPage.getStructuredDataNode()` resolves paths from the page root. If you're already inside a loop over a group (for example, a `#foreach` iterating repeating rows), use `.getChild()` on the loop variable instead. See [Variable Scope in Velocity](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-variable-scope.html) for examples of navigating nested structured data.

### Via `$_.locateFile()`

When you locate a file directly using [`$_.locateFile()`](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html), the returned object is the file asset itself — `.asset` is not needed, and dimensions are available directly on `.dimensions`.

```velocity
#set($image = $_.locateFile("_images/example.webp", "${currentPageSiteName}"))
$image.dimensions.width
$image.dimensions.height
```

## Using an Index Block

When aggregating images via an Index Block, width and height are available as child nodes on each `system-file` result.

> **Index Block Setup**
>
> For dimension nodes to be present in the output, the Index Block must be configured correctly:
>
> - Under **Indexed Asset Content**, select **Regular Content**
> - Under **Indexed Asset Types**, check **Include Files**

With those settings in place, the Index Block produces XML with a `system-file` entry per image, and each entry contains `width` and `height` child nodes:

```xml
<​system-index-block name="all-images" type="folder">
  <​system-file id="...">
    <name>example.png</name>
    <path>/_images/example.png</path>
    <link>site://Example Site/_images/example.png</link>
    <file-size>22868</file-size>
    <width>625</width>
    <height>181</height>
  </​system-file>
</​system-index-block>
```

Loop over the results and retrieve each image's dimensions using `.getChild()`:

```velocity
#set($images = $_XPathTool.selectNodes($contentRoot, "/system-index-block/system-file"))

#foreach($image in $images)
  $image.getChild("width").value
  $image.getChild("height").value
#end
```