---
title: Image
description: Image element api.
---

import SlintProperty from '@slint/common-files/src/components/SlintProperty.astro';
import CodeSnippetMD from '@slint/common-files/src/components/CodeSnippetMD.astro';
import Link from '@slint/common-files/src/components/Link.astro';

<CodeSnippetMD imagePath="/src/assets/generated/image-example.png"  imageWidth="300" imageHeight="200"  imageAlt='image example'>
```slint
Image {
    source: @image-url("mini-banner.png");
}
```
</CodeSnippetMD>

Use the `Image` element to display an <Link type="ImageType" label="image" />.

## Properties

### colorize
<SlintProperty propName="colorize" typeName="brush">
When set, the image is used as an alpha mask and is drawn in the given color (or with the gradient).
<CodeSnippetMD imagePath="/src/assets/generated/image-colorize.png"  imageWidth="300" imageHeight="200"  imageAlt='image example'>
```slint
Image {
    source: @image-url("slint-logo-simple-dark.png");
    colorize: darkorange;
}
```
</CodeSnippetMD>
</SlintProperty>

### horizontal-alignment
<SlintProperty propName="horizontal-alignment" typeName="enum" enumName="ImageHorizontalAlignment" defaultValue='center'>
The horizontal alignment of the image within the element.
</SlintProperty>
### vertical-alignment
<SlintProperty propName="vertical-alignment" typeName="enum" enumName="ImageVerticalAlignment" defaultValue='center'>
The vertical alignment of the image within the element.
</SlintProperty>


## Image Tiling
### horizontal-tiling
<SlintProperty propName="horizontal-tiling" typeName="enum" enumName="ImageTiling" defaultValue='none'>
How the image is tiled horizontally.
</SlintProperty>

### vertical-tiling
<SlintProperty propName="vertical-tiling" typeName="enum" enumName="ImageTiling" defaultValue='none'>

<CodeSnippetMD imagePath="/src/assets/generated/image-horizontal-repeat.png"  imageWidth="400" imageHeight="400"  imageAlt='image horizontal tiling repeat example'>
```slint
Image {
    width: 400px;
    height: 400px;
    source: @image-url("slint-logo.png");
    horizontal-tiling: repeat;
}
```
</CodeSnippetMD>

<CodeSnippetMD imagePath="/src/assets/generated/image-horizontal-round.png"  imageWidth="400" imageHeight="400"  imageAlt='image horizontal tiling round example'>
```slint
Image {
    width: 400px;
    height: 400px;
    source: @image-url("slint-logo.png");
    horizontal-tiling: round;
}
```
</CodeSnippetMD>
<CodeSnippetMD imagePath="/src/assets/generated/image-vertical-repeat.png"  imageWidth="400" imageHeight="400"  imageAlt='image vertical tiling repeat example'>
```slint
Image {
    width: 400px;
    height: 400px;
    source: @image-url("slint-logo.png");
    vertical-tiling: repeat;
}
```
</CodeSnippetMD>

<CodeSnippetMD imagePath="/src/assets/generated/image-vertical-round.png"  imageWidth="400" imageHeight="400"  imageAlt='image vertical tiling round example'>
```slint
Image {
    width: 400px;
    height: 400px;
    source: @image-url("slint-logo.png");
    vertical-tiling: round;
}
```
</CodeSnippetMD>

<CodeSnippetMD imagePath="/src/assets/generated/image-vertical-horizontal-round.png"  imageWidth="400" imageHeight="400"  imageAlt='image vertical and horizontal tiling round example'>
```slint
Image {
    width: 400px;
    height: 400px;
    source: @image-url("slint-logo.png");
    vertical-tiling: round;
    horizontal-tiling: round;
}
```
</CodeSnippetMD>
</SlintProperty>

### image-fit
<SlintProperty propName="image-fit" typeName="enum" defaultValue="`contain` when the `Image` element is part of a layout, `fill` otherwise" enumName="ImageFit">
<CodeSnippetMD imagePath="/src/assets/generated/image-fill.png"  imageWidth="300" imageHeight="200"  imageAlt='image fill example'>
```slint
Image {
    width: 200px; height: 50px;
    source: @image-url("mini-banner.png");
    image-fit: fill;
}
```
</CodeSnippetMD>

<CodeSnippetMD imagePath="/src/assets/generated/image-contain.png"  imageWidth="300" imageHeight="200"  imageAlt='image contain example'>
```slint
Image {
    width: 250px; height: 40px;
    source: @image-url("mini-banner.png");
    image-fit: contain;
}
```
</CodeSnippetMD>

<CodeSnippetMD imagePath="/src/assets/generated/image-cover.png"  imageWidth="300" imageHeight="200"  imageAlt='image cover example'>
```slint
Image {
    width: 250px; height: 250px;
    source: @image-url("mini-banner.png");
    image-fit: cover;
}
```
</CodeSnippetMD>

<CodeSnippetMD imagePath="/src/assets/generated/image-preserve.png"  imageWidth="400" imageHeight="400"  imageAlt='image preserve example'>
```slint
Image {
    width: 400px; height: 400px;
    source: @image-url("mini-banner.png");
    image-fit: preserve;
}
```
</CodeSnippetMD>

</SlintProperty>
### image-rendering
<SlintProperty propName="image-rendering" typeName="enum" enumName="ImageRendering" defaultValue='smooth'>

<CodeSnippetMD imagePath="/src/assets/generated/image-smooth.png"  imageWidth="300" imageHeight="300"  imageAlt='image smooth example'>
```slint
Image {
    width: 800px;
    source: @image-url("mini-banner.png");
    image-rendering: smooth;
}
```
</CodeSnippetMD>

<CodeSnippetMD imagePath="/src/assets/generated/image-pixelated.png"  imageWidth="300" imageHeight="300"  imageAlt='image pixelated example'>
```slint
Image {
    width: 800px;
    source: @image-url("mini-banner.png");
    image-rendering: pixelated;
}
```
</CodeSnippetMD>

</SlintProperty>

## Source Properties

### source
<SlintProperty propName="source" typeName="image">

The `image` type is a reference to an image. It's defined using the `@image-url("...")` construct.
The address within the `@image-url` function must be known at compile time.

Slint looks for images in the following places:

1. The absolute path or the path relative to the current `.slint` file.
2. The include path used by the compiler to look up `.slint` files.

Access an `image`'s source dimension using its `source.width` and `source.height` properties.

```slint
export component Example inherits Window {
    preferred-width: 150px;
    preferred-height: 50px;

    in property <image> some_image: @image-url("https://slint.dev/logo/slint-logo-full-light.svg");

    Text {
        text: "The image is " + some_image.width + "x" + some_image.height;
    }
}
```

```slint
// nine-slice scaling
export component Example inherits Window {
    width: 100px;
    height: 150px;
    VerticalLayout {
        Image {
            source: @image-url("https://interactive-examples.mdn.mozilla.net/media/examples/border-diamonds.png", nine-slice(30 30 30 30));
        }
    }
}
```

Use the <Link type="ImageType" label="`@image-url` macro" /> to specify the image's path.
</SlintProperty>


### source-clip-x
<SlintProperty propName="source-clip-x" typeName="int"/>
### source-clip-y
<SlintProperty propName="source-clip-y" typeName="int"/>
### source-clip-width
<SlintProperty propName="source-clip-width" typeName="int" defaultValue="source.width - source.clip-x"/>
### source-clip-height
<SlintProperty propName="source-clip-height" typeName="int" defaultValue="source.height - source.clip-y"/>

Properties in source image coordinates that define the region of the source image that is rendered.
By default the entire source image is visible:

## Accessibility

### Alternative text

Consider giving an alternative text description of your image by setting the `accessible-label` property:

```slint
Image {
    width: 100px;
    height: 100px;
    source: @image-url("slint-logo.png");
    accessible-label: "Slint logo";
}
```

### Filtering out images for users of assistive technologies

By default, images have the `accessible-role` property set to `image`.
If your image is purely decorative and doesn't convey any information,
consider removing it from the accessibility tree:

```slint
Image {
    source: @image-url("mini-banner.png");
    accessible-role: none;
}
```
