How to Add Image from Assets Folder in Flutter App

Displaying images is fundamental to creating a visually appealing and user-friendly mobile app. Whether it’s your company logo, custom icons, or placeholder illustrations, bundling images directly with your app ensures they are always available, even when the user is offline.

Fortunately, Flutter makes the process of using local images incredibly straightforward. This guide will walk you through the three simple steps to get your images from a local assets folder onto the screen.

Step 1: Create an assets Folder

First, you need a place to store your image files within your Flutter project. The standard convention is to create an assets folder in the root directory of your project (at the same level as your lib and pubspec.yaml files).

For better organization, we highly recommend creating a sub-folder inside assets specifically for images.

Your project structure should look like this:

my_flutter_app/
├── android
├── assets/
│   └── images/
│       └── my_logo.png
├── ios
├── lib/
│   └── main.dart
└── pubspec.yaml

my_flutter_app/
├── android
├── assets/
│   └── images/
│       └── my_logo.png
├── ios
├── lib/
│   └── main.dart
└── pubspec.yaml

Simply create the assets and images directories and place your image file (e.g., my_logo.png) inside the images folder.

Step 2: Declare Your Assets in pubspec.yaml

Next, you need to tell Flutter which files to include in your app bundle. This is done in the pubspec.yaml file. This step is crucial; if you forget to declare your assets here, Flutter won’t be able to find them.

Open your pubspec.yaml file and locate the flutter section. You’ll need to add an assets subsection.

You have two options: declare files individually or declare an entire directory. Declaring the directory is the most common and convenient approach.

To declare the entire images directory, add the following lines:

YAML

flutter:
  uses-material-design: true

  # To add assets to your application, add an assets section, like this:
  assets:
    - assets/images/

flutter:
  uses-material-design: true

  # To add assets to your application, add an assets section, like this:
  assets:
    - assets/images/

⚠️ Important: YAML files are very sensitive to indentation. The assets: line must be indented with two spaces under the flutter: section, and the line - assets/images/ must be indented with two spaces under assets:. Incorrect indentation is the most common cause of errors in this step.

After saving the pubspec.yaml file, make sure to click the “Pub get” button that appears in your IDE (like VS Code or Android Studio) or run flutter pub get in your terminal.

Step 3: Display the Image with the Image.asset() Widget

Now that you’ve properly configured your assets, you can display any image from the declared folder using the Image.asset() widget.

You just need to provide the full path to the image that you specified in pubspec.yaml.

Here’s a simple example of how to display my_logo.png in the center of the screen:

Dart

import 'package:flutter/material.dart';

class HomeScreen extends StatelessWidget {
  const HomeScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Image from Assets'),
      ),
      body: const Center(
        child: Image.asset('assets/images/my_logo.png'),
      ),
    );
  }
}

import 'package:flutter/material.dart';

class HomeScreen extends StatelessWidget {
  const HomeScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Image from Assets'),
      ),
      body: const Center(
        child: Image.asset('assets/images/my_logo.png'),
      ),
    );
  }
}

And that’s it! When you run your app, Flutter will now build, find the image, and display it.

Customizing Your Image: Size and Fit

Often, you’ll need more control over how an image is displayed. The Image widget comes with several useful properties for this.

• width and height: To explicitly set the dimensions of the image.
• fit: To control how the image should be inscribed into the box. It takes a BoxFit value. Common options include:
  • BoxFit.contain: (Default) The entire image is scaled down to fit, preserving its aspect ratio.
  • BoxFit.cover: The image is scaled up to fill the entire box, cropping it if necessary.
  • BoxFit.fill: The image is stretched to fill the box, which may distort the aspect ratio.

Here’s how you might use these properties:

Dart

Image.asset(
  'assets/images/my_logo.png',
  height: 150,
  width: 150,
  fit: BoxFit.cover,
)

Image.asset(
  'assets/images/my_logo.png',
  height: 150,
  width: 150,
  fit: BoxFit.cover,
)

Best Practice: Handling Device Resolutions

To ensure your images look sharp on all devices, you should provide different versions for various screen pixel densities (e.g., 2.0x for Retina displays, 3.0x for high-res Android screens).

Flutter handles this automatically if you structure your folders correctly.

1. Create sub-folders for each resolution within your images directory:assets/ └── images/ ├── 2.0x/ │ └── my_logo.png ├── 3.0x/ │ └── my_logo.png └── my_logo.png // This is the 1.0x (baseline) version
2. Place the higher-resolution images in the corresponding folders. For example, if your baseline my_logo.png is 100×100 pixels, the 2.0x version should be 200×200 pixels, and the 3.0x version should be 300×300 pixels.

You don’t need to change your code! The Image.asset('assets/images/my_logo.png') call remains the same. Flutter will automatically pick the right image for the device’s pixel ratio.