---
title: Modal
description: A low-level modal layer for blocking background interaction.
---



```kotlin expandable title="ModalDemo.kt" githubUrl="https://github.com/composablehorizons/compose-unstyled/blob/main/demo/src/commonMain/kotlin/com/composeunstyled/demo/modal/ModalDemo.kt"
import androidx.compose.animation.AnimatedVisibility
import androidx.compose.animation.core.animateFloatAsState
import androidx.compose.animation.core.tween
import androidx.compose.animation.fadeIn
import androidx.compose.animation.fadeOut
import androidx.compose.animation.scaleIn
import androidx.compose.animation.scaleOut
import androidx.compose.foundation.Image
import androidx.compose.foundation.LocalIndication
import androidx.compose.foundation.background
import androidx.compose.foundation.border
import androidx.compose.foundation.focusable
import androidx.compose.foundation.gestures.detectTapGestures
import androidx.compose.foundation.interaction.MutableInteractionSource
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.BoxWithConstraints
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.FlowRow
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.widthIn
import androidx.compose.foundation.pager.HorizontalPager
import androidx.compose.foundation.pager.PageSize
import androidx.compose.foundation.pager.rememberPagerState
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.alpha
import androidx.compose.ui.draw.clip
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.graphics.RectangleShape
import androidx.compose.ui.input.key.Key
import androidx.compose.ui.input.key.KeyEventType
import androidx.compose.ui.input.key.key
import androidx.compose.ui.input.key.type
import androidx.compose.ui.input.pointer.pointerInput
import androidx.compose.ui.layout.ContentScale
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.tooling.preview.Preview
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import com.composables.icons.lucide.ArrowLeft
import com.composables.icons.lucide.ArrowRight
import com.composables.icons.lucide.Lucide
import com.composables.uripainter.rememberUriPainter
import com.composeunstyled.EscapeHandler
import com.composeunstyled.Modal
import com.composeunstyled.Scrim
import com.composeunstyled.Text
import com.composeunstyled.UnstyledButton
import com.composeunstyled.UnstyledIcon
import com.composeunstyled.demo.borderToken
import com.composeunstyled.demo.colors
import com.composeunstyled.demo.contentToken
import com.composeunstyled.demo.mutedContentToken
import com.composeunstyled.demo.surfaceToken
import com.composeunstyled.rememberModalState
import com.composeunstyled.theme.Theme
import kotlinx.coroutines.launch

@Preview
@Composable
fun ModalDemo() {
  data class GalleryItem(val url: String, val description: String)

  val galleryItems = listOf(
    GalleryItem(
      "https://images.unsplash.com/photo-1472214103451-9374bd1c798e" +
        "?q=80&w=1080&auto=format&fit=crop",
      "Golden wheat field",
    ),
    GalleryItem(
      "https://images.unsplash.com/photo-1469474968028-56623f02e42e" +
        "?q=80&w=1080&auto=format&fit=crop",
      "Mountain landscape",
    ),
    GalleryItem(
      "https://images.unsplash.com/photo-1500534623283-312aade485b7" +
        "?q=80&w=1080&auto=format&fit=crop",
      "Sunlit forest",
    ),
    GalleryItem(
      "https://images.unsplash.com/photo-1507525428034-b723cf961d3e" +
        "?q=80&w=1080&auto=format&fit=crop",
      "Ocean wave",
    ),
    GalleryItem(
      "https://images.unsplash.com/photo-1501785888041-af3ef285b470" +
        "?q=80&w=1080&auto=format&fit=crop",
      "Mountain lake at dawn",
    ),
    GalleryItem(
      "https://images.unsplash.com/photo-1448375240586-882707db888b" +
        "?q=80&w=1080&auto=format&fit=crop",
      "Misty pine forest",
    ),
  )
  val modalState = rememberModalState(initiallyVisible = false)
  val modalFocusRequester = remember { FocusRequester() }
  val pagerState = rememberPagerState(pageCount = { galleryItems.size })
  val coroutineScope = rememberCoroutineScope()
  var selectedIndex by remember { mutableIntStateOf(0) }
  val canGoPrevious = pagerState.currentPage > 0
  val canGoNext = pagerState.currentPage < galleryItems.lastIndex
  val previousButtonAlpha by animateFloatAsState(
    targetValue = if (canGoPrevious) 1f else 0.33f,
    animationSpec = tween(durationMillis = 180),
  )
  val nextButtonAlpha by animateFloatAsState(
    targetValue = if (canGoNext) 1f else 0.33f,
    animationSpec = tween(durationMillis = 180),
  )

  LaunchedEffect(modalState.transitionState.targetState, selectedIndex) {
    if (modalState.transitionState.targetState) {
      pagerState.scrollToPage(selectedIndex)
      modalFocusRequester.requestFocus()
    }
  }

  Box(
    modifier = Modifier
      .fillMaxSize()
      .padding(24.dp),
    contentAlignment = Alignment.Center,
  ) {
    Column(
      modifier = Modifier.widthIn(max = 420.dp).fillMaxWidth(),
      horizontalAlignment = Alignment.CenterHorizontally,
      verticalArrangement = Arrangement.spacedBy(12.dp),
    ) {
      Text(
        "Select a photo to preview",
        color = Theme[colors][contentToken],
        fontSize = 14.sp,
        fontWeight = FontWeight.Medium,
      )

      FlowRow(
        horizontalArrangement = Arrangement.spacedBy(8.dp, Alignment.CenterHorizontally),
        verticalArrangement = Arrangement.spacedBy(8.dp),
        modifier = Modifier.fillMaxWidth(),
      ) {
        galleryItems.forEachIndexed { index, item ->
          UnstyledButton(
            onClick = {
              selectedIndex = index
              modalState.transitionState.targetState = true
            },
            modifier = Modifier
              .size(110.dp, 72.dp)
              .clip(RectangleShape)
              .background(Theme[colors][surfaceToken])
              .border(1.dp, Theme[colors][borderToken], RectangleShape),
            indication = LocalIndication.current,
          ) {
            Image(
              painter = rememberUriPainter(item.url),
              contentDescription = item.description,
              modifier = Modifier.fillMaxSize(),
              contentScale = ContentScale.Crop,
            )
          }
        }
      }
    }

    Modal(
      state = modalState,
      onKeyEvent = { event ->
        if (event.type != KeyEventType.KeyDown) return@Modal false

        when (event.key) {
          Key.DirectionLeft -> {
            if (canGoPrevious) {
              coroutineScope.launch {
                pagerState.animateScrollToPage(pagerState.currentPage - 1)
              }
            }
            true
          }

          Key.DirectionRight -> {
            if (canGoNext) {
              coroutineScope.launch {
                pagerState.animateScrollToPage(pagerState.currentPage + 1)
              }
            }
            true
          }

          else -> false
        }
      },
    ) {
      EscapeHandler {
        modalState.transitionState.targetState = false
      }
      Scrim(
        enter = fadeIn(tween(durationMillis = 220)),
        exit = fadeOut(tween(durationMillis = 180)),
      )

      Box(
        modifier = Modifier
          .fillMaxSize()
          .focusRequester(modalFocusRequester)
          .focusable()
          .pointerInput(Unit) {
            detectTapGestures { modalState.transitionState.targetState = false }
          },
        contentAlignment = Alignment.Center,
      ) {
        AnimatedVisibility(
          visibleState = modalState.transitionState,
          enter = scaleIn(animationSpec = tween(220), initialScale = 0.97f) + fadeIn(tween(220)),
          exit = scaleOut(animationSpec = tween(180), targetScale = 0.98f) + fadeOut(tween(180)),
        ) {
          BoxWithConstraints(
            modifier = Modifier
              .fillMaxSize()
              .padding(vertical = 20.dp),
            contentAlignment = Alignment.Center,
          ) {
            Box(
              modifier = Modifier
                .fillMaxWidth()
                .widthIn(max = 900.dp)
                .pointerInput(Unit) { detectTapGestures { } },
              contentAlignment = Alignment.Center,
            ) {
              HorizontalPager(
                state = pagerState,
                pageSize = PageSize.Fill,
                pageSpacing = 18.dp,
                contentPadding = PaddingValues(horizontal = 34.dp),
                modifier = Modifier
                  .fillMaxWidth()
                  .padding(vertical = 20.dp),
              ) { page ->
                Image(
                  painter = rememberUriPainter(galleryItems[page].url),
                  contentDescription = galleryItems[page].description,
                  modifier = Modifier
                    .fillMaxSize()
                    .clip(RectangleShape)
                    .background(Theme[colors][mutedContentToken]),
                  contentScale = ContentScale.Crop,
                )
              }

              UnstyledButton(
                onClick = {
                  coroutineScope.launch {
                    pagerState.animateScrollToPage(pagerState.currentPage - 1)
                  }
                },
                enabled = canGoPrevious,
                interactionSource = remember { MutableInteractionSource() },
                modifier = Modifier
                  .align(Alignment.CenterStart)
                  .padding(start = 16.dp)
                  .clip(CircleShape)
                  .background(Theme[colors][surfaceToken])
                  .border(1.dp, Theme[colors][borderToken], CircleShape)
                  .alpha(previousButtonAlpha),
                indication = LocalIndication.current,
              ) {
                Box(Modifier.padding(12.dp)) {
                  UnstyledIcon(
                    imageVector = Lucide.ArrowLeft,
                    contentDescription = "Previous image",
                  )
                }
              }

              UnstyledButton(
                onClick = {
                  coroutineScope.launch {
                    pagerState.animateScrollToPage(pagerState.currentPage + 1)
                  }
                },
                enabled = canGoNext,
                interactionSource = remember { MutableInteractionSource() },
                modifier = Modifier
                  .align(Alignment.CenterEnd)
                  .padding(end = 16.dp)
                  .clip(CircleShape)
                  .background(Theme[colors][surfaceToken])
                  .border(1.dp, Theme[colors][borderToken], CircleShape)
                  .alpha(nextButtonAlpha),
                indication = LocalIndication.current,
              ) {
                Box(Modifier.padding(12.dp)) {
                  UnstyledIcon(
                    imageVector = Lucide.ArrowRight,
                    contentDescription = "Next image",
                  )
                }
              }
            }
          }
        }
      }
    }
  }
}
```



## Installation

```kotlin
implementation("com.composables:composeunstyled-modal:2.10.0")
```

## Anatomy

```kotlin
Modal(state = state) {
  Scrim()
}
```

## Concepts

- `ModalState` controls whether the modal is visible.
- `Modal` renders content in a modal layer.
- `Scrim` renders a modal overlay that follows the modal transition state.
- `modalFragment()` marks content that should keep the modal mounted during transitions.

## Accessibility

Use higher-level components such as `Dialog` or `UnstyledModalBottomSheet` when you need built-in dismiss behavior and semantics.

## Code Examples

### Showing modal content

Use the `rememberModalState()` function to create the modal state:

```kotlin expandable
val state = rememberModalState(initiallyVisible = true)

Modal(state = state) {
  Scrim()
  Box(Modifier.modalFragment()) {
    BasicText("Modal content")
  }
}
```

### Adding a scrim

Use `Scrim` inside `Modal` content to render a ready-made overlay:

```kotlin expandable
Modal(state = state) {
  Scrim(scrimColor = Color.Black.copy(alpha = 0.4f))
}
```

### Closing a modal from Escape

Use the `onKeyEvent` parameter to handle keyboard dismissal:

```kotlin expandable
Modal(
  state = state,
  onKeyEvent = { event ->
    if (event.type == KeyEventType.KeyDown && event.key == Key.Escape) {
      state.transitionState.targetState = false
      true
    } else {
      false
    }
  },
) {
  Box(Modifier.modalFragment()) {
    BasicText("Modal content")
  }
}
```

## API Reference

### ModalState

| Parameter | Type | Description |
|-----------|------|-------------|
| `hasMountedFragments` | `Boolean` |  |
| `isAttachedToWindow` | `Boolean` |  |
| `suspend fun awaitAttachedToWindow()` | `suspend () -> Unit` |  |
### rememberModalState

| Parameter | Type | Description |
|-----------|------|-------------|
| `initiallyVisible` | `Boolean` |  |
### Modal

| Parameter | Type | Description |
|-----------|------|-------------|
| `state` | `ModalState` |  |
| `onKeyEvent` | `(KeyEvent) -> Boolean` |  |
| `content` | `ModalScope.() -> Unit` |  |
### ModalScope.Scrim

| Parameter | Type | Description |
|-----------|------|-------------|
| `modifier` | `Modifier` |  |
| `scrimColor` | `Color` |  |
| `enter` | `EnterTransition` |  |
| `exit` | `ExitTransition` |  |