3 min read

While developing a Flutter app, you may want to display an image in a circle shape for showing a user’s photo on a profile page or in a chat listing. Flutter allows you to design a circular image in multiple ways such as using ClipRRect, Container, etc. But in this tutorial, we’ll learn to create a circular image in Flutter using CircleAvatar.

Here’s what we’ll cover:

How to Create a Circular Image in Flutter

The circular image in Flutter is created using a widget called CircleAvatar. CircleAvatar is simply a widget used to display a user profile picture. In the absence of a user’s profile picture, CircleAvatar can display the user’s initials. 

Here are the steps to create a circular image in Flutter:

Step 1: Add the CircleAvatar widget to your dart file.

Step 2: Add backgroundImage parameter.

Step 3: Display local image using AssetImage(‘YOUR-IMAGE-PATH’) and assign it to backgroundImage.

Step 4: Run your app.

Code:

CircleAvatar(
  backgroundImage: AssetImage('assets/images/cat3.png'),
)

Output:

circular image in flutter

Showing Circular Image from Internet

You may want to display a circular image from the internet to show the user’s profile picture.

To show a image from the internet:

  • Simply add the NetworkImage(‘YOUR-IMAGE-PATH’) to the backgroundImage parameter of the CircleAvatar.

Code:

CircleAvatar(
  backgroundImage:
      NetworkImage('https://picsum.photos/id/237/200/300'),
)

Output:

circular image from internet in flutter

Changing Circular Image Size

To change the size of the circular image:

  • Add the radius parameter inside the CircleAvatar and assign the appropriate value.

Code:

CircleAvatar(
  backgroundImage: AssetImage('assets/images/cat3.png'),
  radius: 220,
)

Output:

changing circular image size

Adding Border to Circular Image

Sometimes you may want to display a border around your circular image to stand out in a design.

CircleAvatar doesn’t have any parameter specific to the border. Instead, you can add CircleAvatar (with a smaller radius) inside another CircleAvatar to create a UI-like border.

To create a border:

  • Add one CircleAvatar with backgroundColor set to Colors.black and radius set to 120.
  • Add the child parameter and assign the new CircleAvatar with backgroundImage parameter and radius set to 110 (smaller than the outer CircleAvatar).

Code:

CircleAvatar(
  backgroundColor: Colors.black,
  radius: 120,
  child: CircleAvatar(
    radius: 110,
    backgroundImage: AssetImage('assets/images/cat3.png'),
  ),
)

Output:

adding border to circular image

Changing Background Color

To change the background color of the circular image:

  • Add the backgroundColor parameter inside the CircleAvatar and assign a suitable color.

Code:

CircleAvatar(
  backgroundImage: AssetImage('assets/images/cat3.png'),
  backgroundColor: Colors.greenAccent,
  radius: 120,
)

Output:

change background color

Handling ErrorCallback

Your app might have some issues in showing the image. Without handling ErrorCallback it becomes difficult to identify the issue and fix it.

Here’s how you add ErrorCallback to a circular image:

  • Add the onBackgroundImageError parameter inside the CircleAvatar.
  • Assign the function that you will utilize to understand the issue.

Code:

CircleAvatar(
  backgroundImage: const AssetImage('assets/images/cat3.png'),
  radius: 120,
  onBackgroundImageError: (e, s) {
    debugPrint('image issue, $e,$s');
  },
)

Output:

circle image error handling

Hint: To see ErrorCallback in action, try changing the name of the image in the code and run the app.

Thanks!

Conclusion

In this tutorial, we learned how to create a circular image in Flutter using CircleAvatar. We also learned how to display images from the network, change the size of the circular image and add borders to it.

Take a look at other interesting Flutter tutorials.