- Qt 6.12
- Qt Quick
- QML Types
- QtQuick.VectorImage
- VectorImage
- Qt 6.12.0 Reference Documentation

# VectorImage QML Type

Loads a vector image file and displays it in a Qt Quick scene. More...

Import Statement: | `import QtQuick.VectorImage`
Since: | Qt 6.8
Inherits: | Item

- List of all members, including inherited members

## Properties

- animations `(since 6.10)`
  - animations.loops : int `(since 6.10)`
  - animations.paused : bool `(since 6.10)`
- assumeTrustedSource : bool `(since 6.10)`
- asynchronous : bool `(since 6.12)`
- asynchronousShapes : bool `(since 6.11)`
- fillMode : enumeration
- generatedItem : Item `(since 6.12)`
- preferredRendererType : enumeration
- retainWhileLoading : bool `(since 6.12)`
- source : url
- status : enumeration `(since 6.12)`

## Detailed Description

The VectorImage can be used to load a vector image file and display this as an item in a Qt Quick scene.

It currently supports the `SVG` file format. In addition, Lottie support can be enabled by setting the assumeTrustedSource property to true and including the plugin from the Qt Lottie Animation module.

Note: This complements the approach of loading the vector image file through an Image element: Image creates a raster version of the image at the requested size. VectorImage builds a Qt Quick scene that represents the image. This means the resulting item can be scaled and rotated without losing quality, and it will typically consume less memory than the rasterized version.

## Property Documentation

### animations group

### animations.loops : int `[since 6.10]`

### animations.paused : bool `[since 6.10]`

These properties can be used to control animations in the image, if it contains any.

The `paused` property can be set to true to temporarily pause all animations. When the property is reset to `false`, the animations will resume where they were. By default this property is `false`.

The `loops` property defines the number of times the animations in the document will repeat. By default this property is 1. Any animations that is set to loop indefinitely in the source image will be unaffected by this property. To make all animations in the document repeat indefinitely, the `loops` property can be set to `Animation.Infinite`.

These properties were introduced in Qt 6.10.

### assumeTrustedSource : bool `[since 6.10]`

Setting this to true when loading trusted source files expands support for some features that may be unsafe in an uncontrolled setting. For SVG in particular, this maps to the AssumeTrustedSource option.

When this is set to true, VectorImage will also try to load the image using the Lottie format plugin if this is available. See Qt Lottie Animation for additional information.

By default this property is `false`.

This property was introduced in Qt 6.10.

See also svgtoqml and lottietoqml.

### asynchronous : bool `[since 6.12]`

This property holds whether the image will be loaded asynchronously. When set to to `true`, the UI will remain reactive while the image is loading. The status property can be used to check the current progress.

By default this property is `false`.

This property was introduced in Qt 6.12.

See also asynchronousShapes and status.

### asynchronousShapes : bool `[since 6.11]`

This property controls the {QtQuick.Shapes::Shape::asynchronous}{asynchronous} property of the Shape items in the Quick scene that VectorImage builds to represent the image.

Setting this property to `true` will offload the CPU part of the rendering processing of the shapes to separate worker threads. This can improve CPU utilization and user interface responsiveness.

By default this property is `false`.

This property was introduced in Qt 6.11.

See also asynchronous.

### fillMode : enumeration

This property defines what happens if the width and height of the VectorImage differs from the implicit size of its contents.

Constant | Description
--- | ---
`VectorImage.NoResize` | The contents are still rendered at the size provided by the input.
`VectorImage.Stretch` | The contents are scaled to match the width and height of the `VectorImage`. (This is the default.)
`VectorImage.PreserveAspectFit` | The contents are scaled to fit inside the bounds of the `VectorImage`, while preserving aspect ratio. The actual bounding rect of the contents will sometimes be smaller than the `VectorImage` item.
`VectorImage.PreserveAspectCrop` | The contents are scaled to fill the `VectorImage` item, while preserving the aspect ratio. The actual bounds of the contents will sometimes be larger than the `VectorImage` item.

### generatedItem : Item `[read-only, since 6.12]`

When a vector image file is loaded, this property holds the top level Item of the generated Qt Quick scene. When no file is loaded, this property is `null`.

This property was introduced in Qt 6.12.

### preferredRendererType : enumeration

Requests a specific backend to use for rendering shapes in the `VectorImage`.

Constant | Description
--- | ---
`VectorImage.GeometryRenderer` | Equivalent to Shape.GeometryRenderer. This backend flattens curves and triangulates the result. It will give aliased results unless multi-sampling is enabled, and curve flattening may be visible when the item is scaled.
`VectorImage.CurveRenderer` | Equivalent to Shape.CurveRenderer. With this backend, curves are rendered on the GPU and anti-aliasing is built in. Will typically give better visual results, but at some extra cost to performance.

The default is `VectorImage.GeometryRenderer`.

### retainWhileLoading : bool `[since 6.12]`

This property defines the behavior when the source property is changed and loading happens asynchronously. This is the case when the asynchronous property is set to `true`.

If `retainWhileLoading` is `false` (the default), the old image is discarded immediately, and the component is cleared while the new image is being loaded. If set to `true`, the old image is retained and remains visible until the new one is ready.

Enabling this property can avoid flickering in cases where loading the new image takes a long time. It comes at the cost of some extra memory use while the new image is being loaded.

This property was introduced in Qt 6.12.

See also asynchronous.

### source : url

This property holds the URL of the vector image file to load.

VectorImage currently supports the `SVG` file format. In addition, Lottie support can be enabled by setting the assumeTrustedSource property to true and including the plugin from the Qt Lottie Animation module.

### status : enumeration `[since 6.12]`

This property holds the status of vector image loading. It can be one of:

Constant | Description
--- | ---
`VectorImage.Null` | No vector image has been set
`VectorImage.Ready` | The vector image has been loaded
`VectorImage.Loading` | The vector image is currently being loaded
`VectorImage.Error` | An error occurred while loading the vector image

This property was introduced in Qt 6.12.