DhyanToast

Snackbar-style API for elegant toast notifications with stacked toasts, gestures (tap-to-pause, swipe-to-dismiss), category theming, auto-dismiss and smooth spring animations, customizable visuals and easy integration.

#material3
#gestures
#design-system
#compose-ui
#compose-multiplatform
#compose
#animation

Suggest an edit

Android JVMJVMKotlin/NativeWasmJS

GitHub stars19

AuthorsAndroidPoet

Open issues0

LicenseApache License 2.0

Creation date3 months ago

Last activity3 months ago

Latest release0.0.1 (3 months ago)

GitHub repository Wiki page

DhyānToast

🍞 A powerful and elegant toast notification library for Compose Multiplatform with gestures, animations, and theming support.

Features

🎯 Snackbar-style API - Familiar API similar to Material3 Snackbar
📚 Stacked Toasts - Display multiple toasts with smooth animations
👆 Gesture Support - Tap to pause, swipe to dismiss
🎨 Category-based Theming - Success, Error, Warning, General, and Custom categories
⏱️ Auto-dismiss - Configurable auto-dismiss with pause on interaction
🎭 Smooth Animations - Spring-based animations for natural feel
📱 Compose Multiplatform - Android, iOS, Desktop, and Web support
🔧 Highly Customizable - Custom themes, colors, shapes, and icons
🏗️ Easy Integration - Works seamlessly with Material3 Scaffold

Quick Start

@Composable
fun App() {
  val toastHostState = rememberToastHostState()
  val scope = rememberCoroutineScope()

  ToastScaffold(
    toastHost = { ToastHost(hostState = toastHostState) }
  ) { paddingValues ->
    Button(
      onClick = {
        scope.launch {
          toastHostState.showToast(
            message = "Hello, Toast!",
            category = ToastCategory.Success
          )
        }
      }
    ) {
      Text("Show Toast")
    }
  }
}

Include in your project

Gradle

Add the dependency below to your module's build.gradle file:

dependencies {
    implementation("io.github.androidpoet:dhyantoast:$version")
}

Kotlin Multiplatform

Add the dependency below to your module's build.gradle.kts file:

sourceSets {
    commonMain.dependencies {
        implementation("io.github.androidpoet:dhyantoast:$version")
    }
}

Or using the older syntax:

sourceSets {
    val commonMain by getting {
        dependencies {
            implementation("io.github.androidpoet:dhyantoast:$version")
        }
    }
}

Usage

DhyānToast follows the same pattern as Material3's Snackbar API, making it familiar and easy to use.

Basic Setup

@Composable
fun MyApp() {
  // 1. Create toast host state
  val toastHostState = rememberToastHostState()
  val scope = rememberCoroutineScope()

  // 2. Use ToastScaffold instead of regular Scaffold
  ToastScaffold(
    toastHost = {
      ToastHost(
        hostState = toastHostState,
        alignment = ToastAlignment.Bottom,
        autoDismissEnabled = true,
        autoDismissDelay = 3000L
      )
    }
  ) { paddingValues ->
    // Your content here
    Button(
      onClick = {
        scope.launch {
          // 3. Show toasts from coroutines
          toastHostState.showToast(
            message = "Operation completed!",
            category = ToastCategory.Success
          )
        }
      }
    ) {
      Text("Show Toast")
    }
  }
}

Show Different Toast Categories

// Success toast
toastHostState.showToast(
  message = "Operation completed successfully!",
  title = "Success",
  category = ToastCategory.Success
)

// Error toast
toastHostState.showToast(
  message = "Something went wrong!",
  title = "Error",
  category = ToastCategory.Error
)

// Warning toast
toastHostState.showToast(
  message = "Please check your input",
  title = "Warning",
  category = ToastCategory.Warning
)

// General/Info toast
toastHostState.showToast(
  message = "Here's some useful information",
  category = ToastCategory.General
)

// Custom category
toastHostState.showToast(
  message = "Custom notification",
  category = ToastCategory.Custom("analytics")
)

Customizing Toast Theme

val toastTheme = ToastTheme(
  success = ToastCategoryStyle(
    backgroundColor = Color(0xFF4CAF50),
    textColor = Color.White,
    icon = Icons.Default.Check
  ),
  error = ToastCategoryStyle(
    backgroundColor = Color(0xFFF44336),
    textColor = Color.White,
    icon = Icons.Default.Close
  ),
  warning = ToastCategoryStyle(
    backgroundColor = Color(0xFFFF9800),
    textColor = Color.White,
    icon = Icons.Default.Warning
  )
)

ToastHost(
  hostState = toastHostState,
  theme = toastTheme,
  showCloseButton = true,
  alignment = ToastAlignment.Top,
  visibleCount = 3
)

Advanced Configuration

ToastHost(
  hostState = toastHostState,
  alignment = ToastAlignment.Top,          // Top or Bottom
  autoDismissEnabled = true,               // Auto-dismiss toasts
  autoDismissDelay = 3000L,               // 3 seconds
  visibleCount = 3,                        // Max visible toasts in stack
  categories = listOf(                     // Filter specific categories
    ToastCategory.Success,
    ToastCategory.Error
  ),
  maxWidth = 400.dp,                       // Max width on larger screens
  contentPadding = PaddingValues(16.dp),  // Padding around toasts
  showCloseButton = true,                  // Show close button
  theme = toastTheme                       // Custom theme
)

Custom Toast UI

You can provide your own toast composable for completely custom UI:

ToastHost(
  hostState = toastHostState,
  toast = { toastData ->
    // Your custom toast UI
    Surface(
      modifier = Modifier.fillMaxWidth().padding(8.dp),
      shape = RoundedCornerShape(16.dp),
      color = MaterialTheme.colorScheme.primary
    ) {
      Row(modifier = Modifier.padding(16.dp)) {
        Text(
          text = toastData.message,
          color = MaterialTheme.colorScheme.onPrimary
        )
      }
    }
  }
)

Managing Toasts

// Clear all toasts
toastHostState.clearAll()

// Dismiss a specific toast
toastData.dismiss()

Gestures & Interactions

DhyānToast supports intuitive gesture-based interactions:

Tap to Pause

Tap any toast to pause auto-dismiss for all toasts
Toasts will expand to show all visible items in the stack
Tap again to resume auto-dismiss

Swipe to Dismiss

Swipe up (when aligned to top) to dismiss a toast
Swipe down (when aligned to bottom) to dismiss a toast
Smooth spring-based animations follow your finger

Close Button

Optional close button (×) on each toast
Enable with showCloseButton = true

Animations

Spring-based animations for natural feel
Smooth stacking animations when toasts appear/disappear
Fade and scale effects for visual polish
Configurable dampingRatio and stiffness for custom feel

Platform Support

DhyānToast works on all Compose Multiplatform targets:

Platform	Status
Android	✅ Supported
iOS	✅ Supported
Desktop (JVM)	✅ Supported
Web (JS/WASM)	✅ Supported
macOS	✅ Supported

DhyānToast vs Snackbar

While both use similar APIs, they serve different purposes:

Feature	DhyānToast	Material3 Snackbar
Multiple notifications	✅ Stacked toasts	❌ One at a time
Gesture interactions	✅ Tap to pause, swipe to dismiss	❌ Limited
Auto-dismiss	✅ Configurable per toast	⚠️ Fixed duration
Category theming	✅ Success, Error, Warning, etc.	❌ Manual styling
Stack management	✅ Visible count control	N/A
Alignment	✅ Top or Bottom	⚠️ Bottom only
Use case	Non-critical notifications	Actions with undo

Use DhyānToast when:

You need to show multiple notifications simultaneously
You want category-based styling (success, error, warning)
You need gesture-based interactions
You want notifications at the top of the screen

Use Snackbar when:

You need a single, action-oriented message
You want to provide an "Undo" action
You prefer Material Design's standard bottom placement
You need integration with Material3's standard components

API Components

ToastHostState

showToast() - Show a new toast notification
clearAll() - Clear all active toasts
Similar to SnackbarHostState from Material3

ToastHost

Main composable for displaying toasts
Configurable alignment, auto-dismiss, theming
Support for custom toast UI

ToastScaffold

Drop-in replacement for Material3 Scaffold
Adds toastHost parameter while maintaining all Scaffold features
Works with topBar, bottomBar, snackbarHost, floatingActionButton, etc.

ToastCategory

ToastCategory.Success - Success notifications
ToastCategory.Error - Error messages
ToastCategory.Warning - Warning alerts
ToastCategory.General - General information
ToastCategory.Custom(name) - Custom categories

ToastAlignment

ToastAlignment.Top - Show toasts at top of screen
ToastAlignment.Bottom - Show toasts at bottom of screen

Why DhyānToast?

"Dhyān" (ध्यान) means "attention" or "focus" in Sanskrit. This library is designed to grab user attention elegantly with:

Non-intrusive - Toasts appear smoothly without blocking content
Stackable - Multiple notifications without overwhelming the UI
Dismissable - Easy gesture controls for user convenience
Themed - Category-based styling for instant recognition
Accessible - Clear visual hierarchy and readable text

Best Practices

Performance

Use visibleCount to limit visible toasts and maintain performance
Clear toasts when navigating away: toastHostState.clearAll()
Use appropriate autoDismissDelay to avoid overwhelming users

UX Guidelines

Success: Use for completed actions (save, upload, sync)
Error: Use for failures that need attention (network errors, validation)
Warning: Use for potential issues (low storage, deprecated features)
General: Use for informational messages (tips, updates)

Accessibility

Keep messages concise and scannable
Use titles for additional context
Icons help with quick visual identification
Auto-dismiss gives users time to read
Tap to pause allows users to read at their own pace

Example Toast Messages

// Good - Clear and actionable
toastHostState.showToast(
  title = "File saved",
  message = "Document.pdf saved successfully",
  category = ToastCategory.Success
)

// Avoid - Too verbose
toastHostState.showToast(
  title = "Success",
  message = "The file that you have been working on has been successfully saved to your device storage",
  category = ToastCategory.Success
)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

Find this repository useful? ❤️

Support it by joining stargazers for this repository. ⭐ Also, follow me on GitHub for more cool projects!

License

Copyright 2025 AndroidPoet (Ranbir Singh)

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.