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.

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)

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.

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.

2. Supported Formats

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

---

Properties

Source & Content

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

Layout & Sizing

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

The Width and Height of the image can be controlled via the Default Properties section.

How the Fit property affects image rendering.

How the Alignment property positions an image within its container.

Loading & Error States

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

Property	Description
Placeholder	The type of placeholder to show while a network image is loading. Currently, only BlurHash is supported.
BlurHash String	The BlurHash string that generates the placeholder image.
Error Image	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.

Coming Soon: We are working on adding more placeholder options, such as shimmer effects and low-resolution image previews.

---

Default Properties

The Image widget supports all Default Properties.