CircleImageView — Circular ImageView Widget for Android

Introduction

CircleImageView is a lightweight Android widget that renders images in a circular shape. Widely used for user avatars, profile pictures, and contact thumbnails, it extends ImageView and uses a BitmapShader-based approach for fast, hardware-accelerated circular rendering without allocating extra bitmaps.

What CircleImageView Does

• Renders any image source (drawable, bitmap, URI) as a perfect circle
• Adds configurable circular borders with custom width, color, and overlay options
• Works as a drop-in replacement for standard ImageView in XML layouts
• Supports all ImageView scale types with automatic circular clipping
• Integrates with image loading libraries like Glide, Picasso, and Coil without extra configuration

Architecture Overview

CircleImageView uses a BitmapShader to draw the image content inside a circular path on the Canvas. The shader is applied to a Paint object, and the view draws a filled circle using that paint. Borders are drawn as a separate circle stroke on top. This approach avoids creating intermediate bitmap copies, keeping memory allocation minimal and rendering fast even on older devices.

Setup & Configuration

• Add the circleimageview dependency to your module-level build.gradle
• Use CircleImageView in XML layouts as a replacement for ImageView
• Set border width and color via civ_border_width and civ_border_color attributes
• Configure border overlay mode with civ_border_overlay to draw borders on top of the image
• Load images using Glide, Picasso, or Coil with CircleImageView as the target view

Key Features

• Zero-allocation circular rendering using BitmapShader for minimal memory overhead
• Hardware-accelerated drawing compatible with all Android versions from API 14
• Configurable border with independent width, color, and overlay settings
• Drop-in ImageView replacement with full compatibility for existing image loading pipelines
• Tiny library footprint with a single class and no transitive dependencies

Comparison with Similar Tools

• ShapeableImageView (Material Components) — official Material Design widget with shape theming; CircleImageView is lighter and works without Material dependency
• Glide CircleCrop — transformation applied during loading; CircleImageView applies the shape at the view level, separating concerns
• RoundedImageView — supports rounded rectangles and ovals; CircleImageView focuses specifically on circles with a simpler API
• Coil CircleCropTransformation — Kotlin-first image loading transform; CircleImageView is view-level and library-agnostic
• Custom Canvas clipping — manual approach with clipPath; CircleImageView handles anti-aliasing and border rendering correctly out of the box

FAQ

Q: Does it work with Glide and Picasso? A: Yes. Load images into CircleImageView directly without additional transformations. The view handles circular clipping.

Q: Should I use this or ShapeableImageView? A: ShapeableImageView is the Material Components solution for shape theming. CircleImageView is a simpler, lighter option when you only need circular images without the full Material library.

Q: Does it support animated GIFs? A: CircleImageView works with static bitmaps. For animated GIF support with circular clipping, use Glide's CircleCrop transformation instead.

Q: Can I set a placeholder and error drawable? A: Yes. Set placeholders via the image loading library or via android:src in XML. The view clips whatever drawable is set.

Sources

• https://github.com/hdodenhof/CircleImageView
• https://developer.android.com/reference/com/google/android/material/imageview/ShapeableImageView