# 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="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-bb67b2169b2e0fb604f8831130afcc8d3e63fdb7%2Fimage_widget_box_fit.png?alt=media" 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="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-a471866cb3e460abda9981b9a81d14b9d2f6e6fa%2Fimage_alignment.jpg?alt=media" 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](https://docs.digia.tech/ui-building-blocks/widgets/default-properties "mention").

### 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)