# Image

The **Image widget** is used to display images in your application. It's a versatile component that can render various image formats from different sources, with built-in support for placeholders, error states, and advanced layout control.

{% embed url="<https://www.youtube.com/watch?v=ukZoMCppxyk>" %}

Watch this on Youtube: <https://www.youtube.com/watch?v=ukZoMCppxyk>

### Core Concepts

#### 1. Image Sources: Network vs. Asset

You can load images from two primary sources:

* **Network**: Loads an image directly from a URL. This is ideal for dynamic content, like user profile pictures or images from an API.
* **Asset**: Loads an image that is part of your project's assets. For this to work, you must first upload the image in the **Settings > Local Assets** section of the dashboard. This creates a "Local Asset" that you can then select from a dropdown.

{% hint style="warning" %}
**For SDK Integrations:** When using an `Asset` image, ensure the image file is included in your Flutter project at the exact path you specified when creating the Local Asset on the dashboard.
{% endhint %}

#### 2. Supported Formats

The Image widget supports a wide range of popular formats: `png`, `jpg`, `jpeg`, `gif`, `webp`, `svg`, `avif`

***

### Properties

#### Source & Content

<table><thead><tr><th width="176.25390625">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>Source</code></td><td>The source of the image. Can be <code>Network</code> or <code>Asset</code>.</td></tr><tr><td><code>Image URL / Asset</code></td><td>The URL for a network image or the dropdown to select a pre-uploaded asset.</td></tr><tr><td><code>Image Type</code></td><td>Specifies the image format. Options are <code>Image</code>, <code>SVG</code>,<code>Avif</code>, or <code>Auto</code>. In <strong>Auto</strong> mode, the widget automatically determines the best way to render the image based on its source.</td></tr><tr><td><code>SVG Color</code></td><td>If the image is an SVG, this property applies a solid color fill to it, ignoring the original colors within the SVG file.</td></tr></tbody></table>

#### Layout & Sizing

<table><thead><tr><th width="176.25390625">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>Aspect Ratio</code></td><td>Constrains the widget to a specific aspect ratio (e.g., 16/9 for widescreen, 1/1 for a square). This can override the <code>Height</code> if <code>Width</code> is also set.</td></tr><tr><td><code>Fit</code></td><td>Controls how the image should be sized and positioned within its bounds if its dimensions do not match the widget's dimensions. Options include <code>None</code>, <code>Cover</code>, <code>Fill</code>, <code>Contain</code>,<code>Fit Width</code>, <code>Fit Height</code>, and <code>Scale Down</code>.</td></tr><tr><td><code>Alignment</code></td><td>Positions the image within its container if the image is smaller than the container (e.g., when using <code>fit: contain</code>).</td></tr></tbody></table>

{% hint style="info" %}
The `Width` and `Height` of the image can be controlled via the **Default Properties** section.
{% endhint %}

<figure><img src="/files/iklwTfloeJQzkLI5gWhY" alt="Visual explanation of different Box Fit properties like cover, contain, and fill."><figcaption><p>How the <code>Fit</code> property affects image rendering.</p></figcaption></figure>

<figure><img src="/files/AIwn5yTa2WaVO5ceXxPD" alt="Visual explanation of different Alignment properties like top-left, center, and bottom-right."><figcaption><p>How the <code>Alignment</code> property positions an image within its container.</p></figcaption></figure>

#### Loading & Error States

These properties enhance the user experience by providing feedback while the image is loading or if it fails to load.

<table><thead><tr><th width="176.25390625">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>Placeholder</code></td><td>The type of placeholder to show while a network image is loading. Currently, only <code>BlurHash</code> is supported.</td></tr><tr><td><code>BlurHash String</code></td><td>The BlurHash string that generates the placeholder image.</td></tr><tr><td><code>Error Image</code></td><td>A fallback image to display if the primary image fails to load. To select an error image, you must first upload it as a Local Asset in the dashboard.</td></tr></tbody></table>

{% hint style="info" %}
**Coming Soon:** We are working on adding more placeholder options, such as shimmer effects and low-resolution image previews.
{% endhint %}

***

### Default Properties

The Image widget supports all [Default Properties](/ui-building-blocks/widgets/default-properties.md).

### Use Cases

You’ll typically use **Image** for:

* **Branding**
  * App logo, brand mark, partner logos
  * Hero images on onboarding or home screens
* **Content Visuals**
  * Product photos in e-commerce
  * Banners, promos, and campaign creatives
  * Thumbnails for articles, videos, or podcasts
* **Context & Illustration**
  * Empty state illustrations (“No orders yet”, “No notifications”)
  * Informational graphics in guides or feature highlights
  * Icons or decorative visuals to support text
* **User-Related Media**
  * Profile pictures or avatars
  * Uploaded images (receipts, documents, screenshots)
  * Gallery or carousel views
* **Feedback & Status**
  * Success / error / warning illustrations
  * Badges or stamps (NEW, SALE, VERIFIED)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digia.tech/ui-building-blocks/widgets/content-display-widgets/image.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.