Skip to content

3.0.0

Latest

Choose a tag to compare

@Moriafly Moriafly released this 02 Nov 01:55
· 30 commits to main since this release

3.0.0

November 2, 2026

SaltUI 3.0 is the first stable release of the 3.0 line. It adds adaptive window state, a Sheet, and Navigation 3 integration as standalone modules, brings native window decoration and touch input to all three desktop platforms, and redesigns the button and color APIs.

The changes below are relative to 2.9.0-beta02, the last release of the 2.9 line, and include every alpha and beta of 3.0.

Breaking changes are included in this release. APIs marked @UnstableSaltUiApi remain subject to revision.

Installation

commonMain.dependencies {
    implementation("io.github.moriafly:salt-ui:3.0.0")

    // Optional Navigation 3 integration
    implementation("io.github.moriafly:salt-ui-navigation:3.0.0")
}

salt-ui exposes salt-core and salt-adaptive-window through api, so they are not added separately.

Compatibility

  • Kotlin: 2.4.20
  • Compose Multiplatform: 1.12.2
  • Jetpack Compose: 1.12.2
  • Android minSdk: 23, or 24 with salt-ui-navigation
  • Android compileSdk: 37
  • JVM target: 21

Breaking Changes

  • Removed ScreenTopBarCollapsed. Use BasicScreen with title, subtitle and toolButtons instead.
  • Deprecated APIs are listed under Deprecations and keep binary compatibility.

Adaptive Window

Added salt-adaptive-window, a shared window-information API for Android, Desktop and iOS:

  • Read the window size in dp, the width size class and the device form factor through LocalSaltAdaptiveWindow.current.
  • Classify widths as Compact below 600 dp, Medium from 600 dp, and Expanded from 840 dp, following the Material 3 breakpoints.
  • Track each Desktop window independently, and use window dimensions rather than screen dimensions on iOS.
  • Read window information without adding a provider at the application or theme level.
  • Override the values with ProvideSaltAdaptiveWindow for previews and test fixtures.

Window size and device form factor are exposed separately. A tablet in a narrow split-screen window can still be Compact, so layouts should follow the available window space.

Sheet

Added com.moriafly.salt.ui.sheet.Sheet, supporting bottom and floating presentations:

  • Chooses Bottom or Floating from the owning window's dimensions, or takes an explicit mode. Floating is used when the window is at least 600 dp wide and 480 dp tall, measured before insets are applied.
  • Supports content, medium, large, fixed-height and fractional height detents, dragging between detents, and drag to dismiss in Bottom mode.
  • Supports expand-first and scroll-first nested scrolling, titles, actions, safe areas and keyboard avoidance.
  • Provides Inset and EdgeToEdge content layouts for bottom padding in scrolling content.
  • Uses interruptible spring animations, including reopening during dismissal.
  • Overlaps outgoing and incoming animations when replacing one sheet with another, with scrims and input coordinated by the owning window.
  • Controls dismissal independently for outside clicks, Back, Escape, dragging and the close button.
  • Exposes SheetState.isHidden and awaitHidden(), so navigation can wait for the exit to finish before removing a page.
  • Clears saveable content state and resets the selected detent after a complete dismissal. retainStateWhenHidden = true restores them after a temporary hide, such as returning to a parent sheet.

Keep the Sheet call in composition and control visibility through visible so its exit animation can finish. Only one Sheet per owning window may have visible = true.

Navigation

Added salt-ui-navigation, which integrates Navigation 3:

  • SaltNavigator keeps a back stack and a forward stack, so forward navigation works the way it does in a browser.
  • rememberSaltNavigator(configuration, initRoute, topLevelRoutes) binds the navigator to rememberNavBackStack and saves the forward stack across configuration changes.
  • Navigating to a route in topLevelRoutes collapses the back stack to a single element, matching bottom-bar and sidebar behaviour.

Components and Theme

  • Added Card, ScreenCard, Layer, LabelValue, ItemLabelValueContainer and Switcher, the last with its morph animation.
  • Added BasicAdaptiveDialog.
  • Added ButtonAppearance and ControlSize. PillButton and BasicPillButton now share button metrics through ControlSize.
  • Added success, warning and error to SaltColors.
  • Added overlay to BasicScreen, titleBarBackdropExtraHeight to BasicScreenStyle, contentPadding to NestedHeaderLayout, and decorationEnabled to Layer.
  • Updated default dimensions, shapes and theme values for Android, Desktop and iOS, and tightened item density on desktop.

Desktop and Window

  • Added native touch input on Linux, with gestures that cooperate with the window manager.
  • Added themed resize cursors on Linux, including pointer style updates at the window edge.
  • Added window shadows and borders for undecorated SaltWindow and SaltDialogWindow on Linux, with antialiased corners.
  • Added multi-finger caption bar input on Windows touch screens.
  • Added native title bar interaction and the Vibrancy window background type on macOS.
  • Fixed clicks failing to restore window focus after switching applications on Linux X11.
  • Fixed window dragging and resizing being unavailable while a Sheet is visible on Linux.
  • Fixed Linux resizer corners being clipped by the client shadow, and window snapping being misaligned with it.
  • Fixed transient stale layouts during window rotation, and stale adaptive window metrics after delayed bounds updates.
  • Limited CaptionBarHitTest to one active instance per SaltUI window.

Fixes

  • Fixed Sheet system bar visibility being inherited by the host activity on Android 10 and earlier.
  • Fixed the Sheet close button remaining visible when dismissal is disabled.
  • Fixed fixed detents being resolved after content was measured.
  • Fixed coordinated scrims drawing an additional native dim layer.
  • Fixed title and subtitle text wrapping, both are now limited to a single line.
  • Fixed Cupertino overscroll not tracking pointers safely, and overscroll losing the gesture direction.

Deprecations

  • saltConfigs() is deprecated. Use SaltConfigs.default(isDarkTheme).
  • lightSaltColors() and darkSaltColors() are deprecated. Use SaltColors.defaultLight() and SaltColors.defaultDark().
  • saltColorsByColorScheme() is deprecated and no longer maintained. Map Material 3 colors through SaltColors.defaultLight() or SaltColors.defaultDark().
  • The SaltDimens.default() overload that takes corner and dialogCorner is deprecated. Use the overload without them.

Dependency Updates

  • Kotlin: 2.3.20 → 2.4.20.
  • Compose Multiplatform: 1.11.0-beta02 → 1.12.2.
  • Jetpack Compose: 1.11.0-beta02 → 1.12.2.
  • Android Gradle Plugin: 8.13.2 → 9.1.1.
  • Navigation 3: 1.1.0-beta01 → 1.2.0-rc01.
  • navigationevent: 1.1.0-alpha01 → 1.1.0.
  • Haze: 1.7.2 → 2.0.1. haze-materials is split into haze-blur and haze-blur-materials, so projects that depend on it must update the coordinate.
  • Lazy list and pager sources synced with Jetpack Compose 1.12.0, including the beyondBoundsItemCount overloads added in this release.

Documentation Updates

  • Rewrote the README for 3.0.0, including the artifact list, requirements and usage for adaptive window and navigation.
  • Added the 3.0.0 changelog in English and Chinese.