# CircleImageView — Circular ImageView Widget for Android

> A fast circular ImageView implementation for Android that renders any image source as a perfect circle with optional border and shadow support.

## Install

Save in your project root:

# CircleImageView — Circular ImageView Widget for Android

## Quick Use
```gradle
implementation 'de.hdodenhof:circleimageview:3.1.0'
```
```xml
<de.hdodenhof.circleimageview.CircleImageView
    android:layout_width="96dp"
    android:layout_height="96dp"
    android:src="@drawable/avatar"
    app:civ_border_width="2dp"
    app:civ_border_color="#FFFFFF"/>
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-df4b10b6
Author: AI Open Source