Download the PHP package victorycodedev/toastkit without Composer

ToastKit

Rich, customizable native toast notifications for NativePHP Mobile.

ToastKit renders toasts as native overlays — Jetpack Compose on Android, SwiftUI on iOS — so they look and feel like part of the operating system. No Blade component is required.

Table of Contents

• ToastKit
  • Table of Contents
  • Feature Highlights
  • Installation
  • Quick Start
  • Basic Toasts
  • Custom Toasts
  • Icons
  • Platform overrides
  • Typography
  • Font resolution
  • Updating Toasts
  • Unique Toasts
  • Native Appearance
  • Opacity
  • Progress \& Loading
  • Animations \& Direction
  • Presets
  • Exceptions
    • Migrating exception catches
  • Dismissing Toasts
  • Actions \& Events
  • Queue \& Stack
  • JavaScript Usage
  • Complete NativeComponent Example
  • Real-world Example with NativePHP Fetch
  • Events
  • Testing
  • API Reference
  • Toast facade
  • PendingToast builder
  • PendingToastUpdate builder
  • Enums
  • Defaults
  • Compatibility
  • Permissions \& Dependencies
  • Contributing
  • License

Feature Highlights

• Five variants — success, error, warning, info, and neutral.
• Rich content — title, message, and icons with per-platform overrides.
• Full customization — position, animation direction, progress, loading, swipe-to-dismiss, close control, colors, corner radius, padding, and shadow.
• Action buttons — a native action button with its own ID and pressed event.
• Queue strategy — FIFO, one toast at a time.
• Stack strategy — up to maxVisible toasts on screen with FIFO overflow.
• Live updates — change a visible or queued toast's message, variant, icon, style, or timer without creating a new toast.
• Unique toasts — suppress duplicate work by a stable semantic key across visible, queued, stacked, and persistent toasts.
• Idempotent dismissal — dismiss by ID or dismiss everything.
• Events — ToastShown, ToastDismissed, and ToastActionPressed.
• JavaScript API — a fluent Toast API for web-facing apps.

Installation

Install the package with Composer:

The service provider is auto-discovered by Laravel. Register the native code (only needed once per app):

Verify it is registered:

Then rebuild your app, since Swift and Kotlin are compiled into it:

Quick Start

ToastKit is fully customizable:

ToastKit is controlled from PHP and renders as a native overlay — you never add a Blade component.

Basic Toasts

Each variant applies sensible native defaults, which any explicit style option overrides.

Custom Toasts

Supported options include title(), icon(), position(), duration(), persistent(), animation(), direction(), progress(), loading(), swipeToDismiss(), dismissible(), action(), and the styling methods background(), foreground(), iconColor(), actionColor(), cornerRadius(), padding(), and shadow(). See the API Reference for the full list.

Icons

icon() accepts the same icon names as NativePHP's <native:icon> component, so any icon you already use in your Blade views works unchanged:

A shared name resolves per platform automatically — SF Symbols on iOS and Material Icons on Android.

Platform overrides

When each platform needs a different symbol, pass the platform-native name directly:

• ios: — an SF Symbol name (dotted, e.g. house.fill, checkmark.circle.fill).
• android: — a Material Icon ligature name (underscored, e.g. shopping_cart, qr_code_2).

You can pass either override on its own:

See NativePHP's Icon name reference for the names guaranteed to work consistently on both platforms.

Typography

Customize the message and title typography independently with text() and titleText(). Every argument is optional — anything left unset falls back to the native defaults (message: base size, medium weight, left-aligned, non-italic; title: left-aligned, non-italic, semibold weight):

Typed enums are available too — ToastTextSize, ToastTextWeight, ToastTextAlign:

Typography updates follow the same sparse rules as the rest of update() — only the supplied values change:

This changes only the message weight; font, size, align, and italic are left untouched.

Font resolution

font delegates to NativePHP's font resolver, so it honors the fonts array in config/native-ui.php. Pass a bundled font file's basename (Inter-Bold) or a config alias (accent, body, headline, …) and ToastKit renders the typeface your app already configured:

A name that can't be resolved falls back to the system font on both platforms. ToastKit does not bundle, download, or register fonts itself — it renders whatever NativePHP resolves.

Updating Toasts

update() changes a visible or queued toast in place, keeping the same ID:

Unique Toasts

Use unique() when one logical operation should have at most one active toast, even if the toast is currently visible, queued, stacked, or persistent:

The key identifies the operation, not the presentation. ToastKit does not deduplicate ordinary toasts by message. Showing the same unique key again is ignored: it does not replace or update the original toast, reset its timer, move it in a queue, or emit another ToastShown event. show() returns the original toast's UUID, so callers can safely keep using the result:

Update or dismiss the active toast without retaining its UUID:

A key remains reserved until the toast has fully left the screen, including its exit animation. It is then reusable after every terminal path: timeout, swipe, action, close/programmatic dismissal, replacement, queue overflow, or dismissAll(). Updating a toast never changes its unique key. Calling updateUnique() or dismissUnique() for a key that is not active throws ToastKitException.

Unique keys also work with presets. Define the key as part of the preset during application boot when that preset represents one specific operation:

The unique key is already included, so callers only use the preset and add any per-toast configuration they need:

Updates are sparse:

• The toast keeps its original ID.
• Only properties you explicitly set change; everything else is preserved.
• A persistent toast becomes timed once you supply a duration().

A message-only update is ideal for live progress:

Native Appearance

ToastKit uses its fully customizable renderer on both platforms by default. Call native() when you want each operating system's current design language instead:

Native mode prioritizes platform appearance. Message, title, variant, icon, action, position, duration, persistence, unique identity, queue/stack behavior, progress, loading, dismissal controls, and swipe behavior remain available. ToastKit-specific colors, typography, corner radius, padding, shadow, animation, and direction are ignored only on a platform where native mode is enabled.

Custom styles are retained in the configuration; native() is not a reset. This lets one platform remain fully customized:

Here iOS uses the system appearance while Android uses ToastKit's custom black appearance. Calling background() before or after native() produces the same result. Use native(ios: false, android: false) to explicitly select the custom renderer on both platforms.

Renderer selection is preserved by sparse updates and can also be changed safely on an existing toast:

On iOS 26 and later, ToastKit uses Apple's system Liquid Glass effect. Earlier supported iOS versions use SwiftUI's native regular material. Android uses the official Material 3 Snackbar component inside ToastKit's existing overlay, retaining the established lifecycle and event pipeline.

Opacity

Opacity is optional and applies to the entire toast, including its content and controls:

If opacity() is never called, ToastKit behaves exactly as before. Accepted values are 0.0–1.0; values outside that range are clamped. Opacity also works in presets and sparse updates:

Progress & Loading

Use determinate progress for work with a known percentage. Values are clamped to 0–100, and updates animate without replacing the toast:

Use loading() when progress is unknown, and loading(false) to stop it:

If a payload contains both progress and loading: true, determinate progress wins. This makes partial updates deterministic while preserving both values in the transport contract.

Animations & Direction

ToastKit supports fade, slide, scale, spring, snap, pop, reveal, and bounce. Direction is independent and accepts auto, left, right, top, or bottom:

auto is the default and derives the motion from the toast position. Reduced-motion platform settings use a short fade instead of spatial or spring motion.

Presets

Define reusable presets during application boot, such as in a service provider:

Each call creates a fresh builder, and options chained afterward override the preset:

Defining the same name again replaces the previous definition. Missing presets throw PresetNotFoundException. All intentional public configuration failures extend ToastKitException. Presets are PHP-only because they are registered in the Laravel application lifecycle.

Small applications can keep these definitions directly in AppServiceProvider::boot(). For larger applications, a convenient optional organization is an App\Toasts\ToastPresets class with a static register() method, called from AppServiceProvider::boot(). ToastKit does not generate or require this class; it simply keeps a longer preset catalog out of the provider. Precedence is: ToastKit defaults → preset → per-toast configuration → sparse update configuration.

Then call ToastPresets::register() from your application's AppServiceProvider::boot():

You may instead keep all toast presets in a dedicated service provider, such as ToastServiceProvider:

Register that provider using your Laravel application's normal provider registration, for example in bootstrap/providers.php:

Exceptions

ToastKit exposes one package-owned exception hierarchy:

Catch ToastKitException when you want to handle every error intentionally raised by ToastKit:

Use a specific subclass when the application can recover from one particular condition, such as a missing preset:

Migrating exception catches

ToastKit exceptions no longer extend PHP's InvalidArgumentException. Applications that previously caught that exception for ToastKit calls should use the package base exception instead:

Dismissing Toasts

Dismiss everything at once:

Dismissals are idempotent — dismissing an ID that is already gone is a no-op.

Actions & Events

Add a native action button and handle its press:

Pressing an action emits ToastActionPressed and dismisses the toast.

The other events follow the same pattern:

See Events for the full event reference.

Queue & Stack

The default strategy is a FIFO queue — one toast at a time:

Each toast appears after the previous one finishes. Its duration only begins once it becomes visible.

The stack strategy shows up to maxVisible toasts at once:

When the stack is full, additional toasts wait and are admitted in FIFO order as existing toasts dismiss.

JavaScript Usage

ToastKit ships a JavaScript library in resources/js/ (Composer-installed at vendor/victorycodedev/toastkit/resources/js/). There is no published npm package — copy the files into your app or bundle them with your build tool.

Updates mirror the PHP API:

Unique toasts have the same semantics in JavaScript:

Raw bridge functions are also exported:

Complete NativeComponent Example

Blade screen using native components:

Real-world Example with NativePHP Fetch

ToastKit pairs naturally with the Fetch (Http) package for upload/download progress. Fetch is not a ToastKit dependency - this is an optional integration example.

Then handle the Fetch events to drive live toast updates:

Refer to your Fetch package's documentation for its exact API surface.

Events

ToastKit dispatches three events. Listen with NativePHP's #[On] attribute:

ToastDismissReason declares timeout, swipe, programmatic, action, and replaced; the native renderers currently emit timeout, swipe, programmatic, and action.

Testing

Run the PHP suite:

Run the JavaScript suite:

ToastKit registers FakeBridge macros so your own tests can assert on toast traffic using domain vocabulary — no emulator or device required:

Available macros:

To test how a screen reacts to a ToastKit event, deliver the event yourself with NativePHP's emitNative():

API Reference

Toast facade

PendingToast builder

make() and the variant shortcuts return a PendingToast. All methods are chainable; show() sends the toast to the native bridge and returns its ID (a UUID by default, or a custom ID from id()).

PendingToastUpdate builder

Toast::update($id) and Toast::updateUnique($key) return a PendingToastUpdate. It exposes the same configuration methods as PendingToast — except id() and unique(), since identity is fixed — plus a show() method that applies the update. Only properties you explicitly set are sent; everything else is preserved.

Enums

Defaults

Compatibility

ToastKit supports Android and iOS.

Permissions & Dependencies

ToastKit requires no Android permissions and no iOS permission strings. It adds no third-party native dependencies — it relies on the NativePHP host toolchain and the native platform frameworks (Jetpack Compose and SwiftUI).

Contributing

See CONTRIBUTING.md.

License

The MIT License (MIT). See LICENSE.