Flutter: Adding Images - Assets and Image.asset

Adding Images in Flutter

To add images to your Flutter project, you first need to place the images in a folder and then define them as assets in the pubspec.yaml file.

Step 1: Creating Image Folder

Create an image folder in the root directory of your Flutter project (at the same level as the lib folder):

my_flutter_app/
  ├── lib/
  ├── assets/
  │   └── images/
  │       ├── logo.png
  │       ├── profile.jpg
  │       └── banner.png
  ├── pubspec.yaml
  └── ...

Note: The folder name is usually assets, images or assets/images. You can give it any name you want.

Step 2: pubspec.yaml Configuration

Open the pubspec.yaml file and add the assets definition under the flutter: section:

Adding a Single Image

flutter:
  uses-material-design: true
  
  assets:
    - assets/images/logo.png

Adding Entire Folder

flutter:
  uses-material-design: true
  
  assets:
    - assets/images/

If there's a / at the end of the folder path, all files in that folder are added as assets (excluding subfolders).

Example pubspec.yaml

name: my_app
description: My Flutter application.

environment:
  sdk: '>=3.0.0 <4.0.0'

dependencies:
  flutter:
    sdk: flutter

flutter:
  uses-material-design: true
  
  assets:
    - assets/images/
    - assets/icons/

Step 3: Using Images

Image.asset Widget

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

Sizing

Image.asset(
  'assets/images/logo.png',
  width: 200,
  height: 200,
)

Fitting with BoxFit

Image.asset(
  'assets/images/banner.png',
  width: double.infinity,
  height: 200,
  fit: BoxFit.cover, // Fill the area
)

BoxFit values:

• cover: Completely fills the area, crops
• contain: Entire image visible, may leave space
• fill: Fills the area, ratio may be distorted
• fitWidth: Fit to width
• fitHeight: Fit to height
• none: Original size
• scaleDown: Like contain but doesn't enlarge

Multi-Screen Support for Images

You can use different resolution images for different screen densities:

Folder Structure

assets/
  └── images/
      ├── logo.png          (1x - mdpi)
      ├── 1.5x/
      │   └── logo.png      (1.5x - hdpi)
      ├── 2.0x/
      │   └── logo.png      (2x - xhdpi)
      ├── 3.0x/
      │   └── logo.png      (3x - xxhdpi)
      └── 4.0x/
          └── logo.png      (4x - xxxhdpi)

pubspec.yaml

flutter:
  assets:
    - assets/images/logo.png

Note: It automatically detects 1.5x, 2.0x, 3.0x, 4.0x folders, no need to specify separately.

Usage

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

Flutter automatically selects the appropriate image based on the device's density.

Common Mistakes

1. pubspec.yaml Indentation

# ❌ WRONG
flutter:
uses-material-design: true
assets:
  - assets/images/

# ✅ CORRECT
flutter:
  uses-material-design: true
  assets:
    - assets/images/

Indentation is important! Use 2 or 4 spaces.

2. Path Error

// ❌ WRONG
Image.asset('images/logo.png')  // Missing 'assets/'

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

3. Hot Reload Issue

For pubspec.yaml changes:

• Hot reload is not enough
• Do Hot restart (🔄 button)
• Or completely stop and start the app

Summary

Adding images in Flutter:

1. Create folder: assets/images/
2. Add images: PNG, JPG, SVG, etc.
3. Define in pubspec.yaml:

   flutter:
     assets:
       - assets/images/

4. Hot restart
5. Use:

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

Recommendations:

• Create 1.5x, 2.0x, 3.0x folders for multi-resolution
• Use meaningful file names
• Optimize large images
• Use flutter_svg for SVG images
• Use cached_network_image for network images

Images are an important part of the visual identity of Flutter applications. When used correctly, they make your app professional and attractive!