Skip to main content

AsyncPic

The main composable. Handles all image loading, transitions, effects, and callbacks.

@Composable
fun AsyncPic(
    source: ImageSource,
    modifier: Modifier = Modifier,
    contentDescription: String? = null,
    shape: Shape = RectangleShape,
    placeholderUrl: String? = null,
    blurRadius: Int = 0,
    circleCrop: Boolean = false,
    placeholder: @Composable () -> Unit = { DefaultShimmer() },
    placeholderType: ImageSource.PlaceholderType = ImageSource.PlaceholderType.SHIMMER,
    shimmerColor: Color = Color(0xFFF1F5F9),
    shimmerDirection: ImageSource.ShimmerDirection = ImageSource.ShimmerDirection.DIAGONAL,
    error: @Composable () -> Unit = { DefaultError() },
    zoomable: Boolean = false,
    minShimmerTime: Long = 1000,
    contentScale: ContentScale = ContentScale.Crop,
    diskCachePolicy: CachePolicy = CachePolicy.ENABLED,
    memoryCachePolicy: CachePolicy = CachePolicy.ENABLED,
    onPaletteLoaded: ((AsyncPicPalette) -> Unit)? = null,
    onSuccess: (() -> Unit)? = null,
    onError: ((Throwable) -> Unit)? = null,
    parallaxIntensity: Float = 0f,
    transition: AsyncPicTransition = AsyncPicTransition.Standard
)

Parameters​

source​

ImageSource — Required

The image source. One of:

  • ImageSource.Url(value: String) — load from URL
  • ImageSource.Resources(resId: Int) — load from drawable resource
  • ImageSource.Progressive(finalUrl, thumbnailUrl?, blurHash?) — progressive loading

modifier​

Modifier = Modifier

Standard Compose modifier applied to the outer Box.

contentDescription​

String? = null

Accessibility description for screen readers.

shape​

Shape = RectangleShape

Clips the image to any shape. Common values: RoundedCornerShape(16.dp), CircleShape.

note

Shape clipping is applied to the outer Box. When zoomable = true, clipping is deferred to the graphics layer to allow correct pan behavior.

placeholderUrl​

String? = null

A Coil memory cache key for a pre-loaded placeholder image. Useful if you already have a smaller version in the cache.

blurRadius​

Int = 0

Applies CustomBlurTransformation using RenderScript. Range: 0–25. On ImageSource.Progressive, this is applied to the thumbnail layer.

circleCrop​

Boolean = false

Applies Coil's CircleCropTransformation. Alternative to shape = CircleShape — handled at the bitmap level.

placeholder​

@Composable () -> Unit = { DefaultShimmer() }

Custom placeholder composable shown while loading. Overrides placeholderType if supplied.

placeholderType​

ImageSource.PlaceholderType = SHIMMER

Built-in placeholder style:

ValueDescription
SHIMMERAnimated gradient shimmer (default)
SKELETONPulsing opacity block
NONENothing shown while loading

shimmerColor​

Color = Color(0xFFF1F5F9)

Base color for the shimmer gradient. AsyncPic will animate this toward the image's dominant color once loaded (Adaptive Color Morphing).

shimmerDirection​

ImageSource.ShimmerDirection = DIAGONAL

Direction of the shimmer sweep: DIAGONAL, LTR, RTL, TTB, BTT.

error​

@Composable () -> Unit = { DefaultError() }

Composable shown when image fails to load. Default shows a warning icon.

zoomable​

Boolean = false

Enables pinch-to-zoom (1x–4x) and double-tap toggle (1x ↔ 3x).

minShimmerTime​

Long = 1000

Minimum time in milliseconds to show the shimmer/placeholder, even if the image loads faster. Skipped for animated formats (GIF/WebP).

contentScale​

ContentScale = ContentScale.Crop

How the image is scaled to fit its bounds. Standard Compose ContentScale values.

diskCachePolicy​

CachePolicy = CachePolicy.ENABLED

Controls Coil disk caching for this image.

memoryCachePolicy​

CachePolicy = CachePolicy.ENABLED

Controls Coil memory caching for this image.

onPaletteLoaded​

((AsyncPicPalette) -> Unit)? = null

Called after a successful load with 5 extracted color swatches. Called on the main thread via Palette's async generator.

onSuccess​

(() -> Unit)? = null

Called when the image loads successfully.

onError​

((Throwable) -> Unit)? = null

Called when the image fails to load, with the underlying exception.

parallaxIntensity​

Float = 0f

Applies a scroll-based parallax offset. 0f disables it. Recommended range: 0.02f–0.08f.

transition​

AsyncPicTransition = AsyncPicTransition.Standard

The reveal animation when the image finishes loading:

  • AsyncPicTransition.Standard — Coil's default crossfade
  • AsyncPicTransition.ShaderReveal(type, durationMillis) — AGSL shader (Android 13+)