Flutter Image Widget – Complete Guide with Examples - Learn FLUTTER | Revochamp

Name: Flutter Image Widget – Complete Guide with Examples
Availability: InStock
Author: Revochamp

What is the Image Widget?

The Image widget in Flutter displays images from various sources: network URLs, local assets, device file system, or memory. It's a versatile widget that supports many display options, including fit, alignment, repeat, and error handling. Images are loaded asynchronously, and Flutter provides built‑in caching for network images.

Image Constructors

Flutter provides several named constructors to load images from different sources:

- Image.network: Loads an image from a URL.
- Image.asset: Loads an image from the app's asset bundle.
- Image.file: Loads an image from a file on the device.
- Image.memory: Loads an image from a Uint8List (byte array).
- Image: Takes an ImageProvider for more advanced use.

Image from Network

DARTRead-only

Image.network(
  'https://example.com/image.jpg',
  width: 200,
  height: 200,
)

Image.network(
  'https://example.com/image.jpg',
  width: 200,
  height: 200,
)

Network images are cached automatically by Flutter's image cache (up to a limit). You can also control caching with cacheWidth and cacheHeight to downscale the image before decoding.

Image from Assets

First, declare the asset in pubspec.yaml. Then reference it with Image.asset. Flutter automatically selects the correct resolution variant based on the device pixel ratio if you organise images with 2.0x, 3.0x folders.

DARTRead-only

Image.asset('assets/images/logo.png')

Image.asset('assets/images/logo.png')

Image from File

For images from the device file system (e.g., a photo picked by the user), use Image.file. You'll need a File object from dart:io.

DARTRead-only

import 'dart:io';

Image.file(File('/path/to/image.jpg'))

import 'dart:io';

Image.file(File('/path/to/image.jpg'))

Controlling Image Fit

The fit property determines how the image is inscribed into the available space. Common values:

- BoxFit.cover: Scales the image to fill the entire box, cropping if necessary.
- BoxFit.contain: Scales the image to fit within the box while preserving aspect ratio (may leave empty space).
- BoxFit.fill: Stretches the image to fill the box, possibly distorting it.
- BoxFit.fitWidth: Scales to match the box's width, cropping height if needed.
- BoxFit.fitHeight: Scales to match the box's height, cropping width if needed.

DARTRead-only

Image.network(
  'https://example.com/wide.jpg',
  width: 200,
  height: 200,
  fit: BoxFit.cover,
)

Image.network(
  'https://example.com/wide.jpg',
  width: 200,
  height: 200,
  fit: BoxFit.cover,
)

Alignment

When the image is larger than the available space, alignment controls how it is positioned within the box. For example, Alignment.topLeft anchors the image to the top left.

DARTRead-only

Image.network(
  'https://example.com/large.jpg',
  width: 100,
  height: 100,
  alignment: Alignment.center,
)

Image.network(
  'https://example.com/large.jpg',
  width: 100,
  height: 100,
  alignment: Alignment.center,
)

Error Handling

You can handle loading errors with the errorBuilder and frameBuilder. errorBuilder is called when the image fails to load; frameBuilder can show a placeholder while loading.

DARTRead-only

Image.network(
  'https://invalid.url/image.jpg',
  errorBuilder: (context, error, stackTrace) => Icon(Icons.broken_image),
  frameBuilder: (context, child, frame, wasSynchronouslyLoaded) {
    if (wasSynchronouslyLoaded) return child;
    return CircularProgressIndicator();
  },
)

Image.network(
  'https://invalid.url/image.jpg',
  errorBuilder: (context, error, stackTrace) => Icon(Icons.broken_image),
  frameBuilder: (context, child, frame, wasSynchronouslyLoaded) {
    if (wasSynchronouslyLoaded) return child;
    return CircularProgressIndicator();
  },
)

Caching and Performance

Flutter's Image.network uses a memory cache. To have more control over caching (e.g., disk cache), use the cached_network_image package. For large images, set cacheWidth and cacheHeight to avoid decoding the full image.

DARTRead-only

Image.network(
  url,
  cacheWidth: 300,
  cacheHeight: 300,
)

Image.network(
  url,
  cacheWidth: 300,
  cacheHeight: 300,
)

Key Takeaways

- Use Image.network for remote images, Image.asset for bundled assets, Image.file for local files.
- Control image scaling with fit and positioning with alignment.
- Provide errorBuilder and frameBuilder for a better user experience.
- Optimise memory usage with cacheWidth and cacheHeight.
- For advanced caching, consider cached_network_image.

Try it yourself

import 'package:flutter/material.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Image Demo')),
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Image.network(
                'https://picsum.photos/200/200',
                width: 150,
                height: 150,
                fit: BoxFit.cover,
              ),
              SizedBox(height: 20),
              Image.asset('assets/images/flutter_logo.png', width: 100),
            ],
          ),
        ),
      ),
    );
  }
}

Test Your Knowledge

of 4

Which constructor is used to load an image from a URL?

Image.file

Image.asset

Image.network

Image.memory

of 4

What does `BoxFit.cover` do?

Stretches the image to fill the box

Scales the image to fit inside the box

Scales the image to cover the box, possibly cropping

Centers the image without scaling

of 4

How do you handle image loading errors?

errorBuilder

onError

catchError

errorCallback

of 4

How can you limit the memory used by a large network image?

Set `maxWidth` and `maxHeight`

Set `cacheWidth` and `cacheHeight`

Use `resize`

It's automatic

Frequently Asked Questions

How do I display a placeholder while a network image loads?

Use the frameBuilder to show a CircularProgressIndicator until the image is loaded. Alternatively, use the cached_network_image package which provides a built‑in placeholder.

How can I make an image circular?

Wrap the Image widget with ClipOval or use CircleAvatar with backgroundImage. For a ClipOval, set clipBehavior: Clip.antiAlias.

Why is my asset image not showing?

Make sure the asset is declared in pubspec.yaml under flutter.assets, and the path is correct. Also run flutter pub get to ensure assets are included. Check the case sensitivity of the file name.

How do I load an image from a base64 string?

Use Image.memory with the decoded bytes. For example: Image.memory(base64Decode(base64String)).

What's the difference between `Image.network` and `CachedNetworkImage`?

Image.network uses an in‑memory cache, but images are lost when the app restarts. CachedNetworkImage provides disk caching, placeholders, error widgets, and progress indicators out of the box.

Image.network( 'https://invalid.url/image.jpg', errorBuilder: (context, error, stackTrace) => Icon(Icons.broken_image), frameBuilder: (context, child, frame, wasSynchronouslyLoaded) { if (wasSynchronouslyLoaded) return child; return CircularProgressIndicator(); }, )

Try it yourself

import 'package:flutter/material.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Image Demo')),
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Image.network(
                'https://picsum.photos/200/200',
                width: 150,
                height: 150,
                fit: BoxFit.cover,
              ),
              SizedBox(height: 20),
              Image.asset('assets/images/flutter_logo.png', width: 100),
            ],
          ),
        ),
      ),
    );
  }
}

Test Your Knowledge

of 4

Which constructor is used to load an image from a URL?

Image.file

Image.asset

Image.network

Image.memory

of 4

What does `BoxFit.cover` do?

Stretches the image to fill the box

Scales the image to fit inside the box

Scales the image to cover the box, possibly cropping

Centers the image without scaling

of 4

How do you handle image loading errors?

errorBuilder

onError

catchError

errorCallback

of 4

How can you limit the memory used by a large network image?

Set `maxWidth` and `maxHeight`

Set `cacheWidth` and `cacheHeight`

Use `resize`

It's automatic

Frequently Asked Questions

How do I display a placeholder while a network image loads?

Use the frameBuilder to show a CircularProgressIndicator until the image is loaded. Alternatively, use the cached_network_image package which provides a built‑in placeholder.

How can I make an image circular?

Wrap the Image widget with ClipOval or use CircleAvatar with backgroundImage. For a ClipOval, set clipBehavior: Clip.antiAlias.

Why is my asset image not showing?

How do I load an image from a base64 string?

Use Image.memory with the decoded bytes. For example: Image.memory(base64Decode(base64String)).

What's the difference between `Image.network` and `CachedNetworkImage`?

Image.network uses an in‑memory cache, but images are lost when the app restarts. CachedNetworkImage provides disk caching, placeholders, error widgets, and progress indicators out of the box.

Flutter Image Widget – Complete Guide with Examples

Flutter Image Widget – Complete Guide with Examples

What is the Image Widget?

Image Constructors

Image from Network

Image from Assets

Image from File

Controlling Image Fit

Alignment

Error Handling

Caching and Performance

Key Takeaways

Try it yourself

Test Your Knowledge

Frequently Asked Questions

Need help?

Flutter Image Widget – Complete Guide with Examples

Flutter Image Widget – Complete Guide with Examples

What is the Image Widget?

Image Constructors

Image from Network

Image from Assets

Image from File

Controlling Image Fit

Alignment

Error Handling

Caching and Performance

Key Takeaways

Try it yourself

Test Your Knowledge

Frequently Asked Questions

Need help?