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.

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, allowing you to add padding, margins, borders, background colors, and onClick actions.

---

Best Practices

• Optimize Images: For faster load times, especially on mobile, compress your images before uploading them. Use tools like TinyPNG or Squoosh.

• Use Placeholders: For network images, always use a Placeholder like BlurHash. It dramatically improves perceived performance and prevents jarring layout shifts as images load.

• Use SVGs for Icons: For simple icons and logos, prefer SVG over PNG. They are infinitely scalable without losing quality and can be colored dynamically using the SVG Color property.

Mastering Aspect Ratio: To maintain a consistent shape for your image across different screen sizes, use the Aspect Ratio property. For it to work correctly, you must provide either a Width or a Height from the Default Properties, but not both.

• Responsive Width Example: Set Width to 100% and Aspect Ratio to 16/9. The height will adjust automatically.

• Fixed Height Example: Set Height to 200px and Aspect Ratio to 1/1 (a square). The width will adjust automatically.