@expo/ui 55.0.0 → 55.0.2-canary-20260424-7bedc9d

package/CHANGELOG.md

@@ -4,12 +4,114 @@
 
 ### 🛠 Breaking changes
 
+- [iOS] Match `TextField` and `SecureField` API with SwiftUI: replaced `multiline`, `numberOfLines`, `allowNewlines` with `axis` prop. Moved `keyboardType`, `autocorrectionDisabled`, `onSubmit` from props to modifier registry. Renamed events `onValueChanged` → `onValueChange`, `onFocusChanged` → `onFocusChange`, `onSelectionChanged` → `onSelectionChange`. Removed hardcoded `fixedSize`. Added `LineLimitModifier` with `reservesSpace` and range support. Added `OnSubmitModifier` and `KeyboardTypeModifier`. ([#44549](https://github.com/expo/expo/pull/44549) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Match `TextField` API to native Compose: renamed `TextInput` to `TextField`/`OutlinedTextField`, replaced individual keyboard props with `keyboardOptions`/`keyboardActions` matching `KeyboardOptions`/`KeyboardActions`, added `enabled`, `readOnly`, `isError`, `singleLine`, `maxLines`, `minLines`, `shape`, `colors`. Added composable slots: `placeholder`, `leadingIcon`, `trailingIcon`, `prefix`, `suffix`, `supportingText`. Added imperative `focus()`/`blur()` and `onFocusChanged` event. ([#44545](https://github.com/expo/expo/pull/44545) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Match `Icon` API to native: renamed `tintColor` to `tint`. Match `ListItem` API to native: replaced string props with slot sub-components (`HeadlineContent`, `SupportingContent`, `OverlineContent`, `LeadingContent`, `TrailingContent`). Renamed color props to match `ListItemDefaults.colors()`. Added `tonalElevation`, `shadowElevation`. Removed `color`, `onPress`. ([#44054](https://github.com/expo/expo/pull/44054) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Refactored `PullToRefreshBox` indicator props: replaced `loadingIndicatorModifiers` with nested `indicator` prop containing `color`, `containerColor`, and `modifiers`. Added `contentAlignment` prop. ([#44079](https://github.com/expo/expo/pull/44079) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Split `Divider` into `HorizontalDivider` and `VerticalDivider` matching native Compose components. Added `thickness` and `color` props. ([#44035](https://github.com/expo/expo/pull/44035) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Match `AlertDialog` API to native Compose: replaced string props (`title`, `text`, `confirmButtonText`, `dismissButtonText`) with slot sub-components (`AlertDialog.Title`, `AlertDialog.Text`, `AlertDialog.ConfirmButton`, `AlertDialog.DismissButton`, `AlertDialog.Icon`). Removed `visible` prop (use conditional rendering), `onConfirmPressed`/`onDismissPressed` (renamed to `onDismissRequest`), and `confirmButtonColors`/`dismissButtonColors` (replaced with dialog-level `colors`). ([#43997](https://github.com/expo/expo/pull/43997) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Split `Carousel` into `HorizontalCenteredHeroCarousel`, `HorizontalMultiBrowseCarousel`, and `HorizontalUncontainedCarousel` matching native Compose components. Added `HorizontalCenteredHeroCarousel`. ([#44034](https://github.com/expo/expo/pull/44034) by [@nishan](https://github.com/intergalacticspacehighway))
+- [iOS] Renamed Stepper `defaultValue` to `value` and `onValueChanged` to `onValueChange`. ([#43954](https://github.com/expo/expo/pull/43954) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Replace `Picker` with `SingleChoiceSegmentedButtonRow`, `MultiChoiceSegmentedButtonRow`, and `SegmentedButton` components. Replace `RadioButton` `nativeClickable` prop with `onClick` event. ([#43809](https://github.com/expo/expo/pull/43809) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Split `ToggleButton` into separate M3 components: `ToggleButton`, `IconToggleButton`, `FilledIconToggleButton`, `OutlinedIconToggleButton`. Removed `variant`, `text`, `color`, `disabled` props. Added `colors` with checked/unchecked variants. ([#43974](https://github.com/expo/expo/pull/43974) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Match `Switch` API to native: removed `variant` prop and split into separate `Switch` and `Checkbox` components matching native M3 APIs. Renamed `elementColors` to `colors`, `onValueChange` to `onCheckedChange`, removed `color` convenience prop. ([#43887](https://github.com/expo/expo/pull/43887) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Refactored Progress Indicators to match native Compose API: split into `LinearProgressIndicator`, `CircularProgressIndicator`, `LinearWavyProgressIndicator`, `CircularWavyProgressIndicator`. Flattened `elementColors.trackColor` to `trackColor`. Added `strokeCap`, `gapSize`, `strokeWidth` props. ([#43907](https://github.com/expo/expo/pull/43907) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Refactored `Card` to match native Material3 API: split into `Card`/`ElevatedCard`/`OutlinedCard` with type-specific props (`elevation`, `border`). ([#43896](https://github.com/expo/expo/pull/43896) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Split `Button` into separate M3 components: `Button`, `FilledTonalButton`, `OutlinedButton`, `ElevatedButton`, `TextButton`. Removed `variant`, `text`, `leadingIcon`, `trailingIcon`, `color`, `elementColors`, `disabled` props. ([#43859](https://github.com/expo/expo/pull/43859) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Split `IconButton` into separate M3 components: `IconButton`, `FilledIconButton`, `FilledTonalIconButton`, `OutlinedIconButton`. Removed `variant`, `color`, `elementColors`, `disabled`, `onPress` props. ([#43859](https://github.com/expo/expo/pull/43859) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Refactored `Chip` to match native Material3 API: split into `AssistChip`/`FilterChip`/`InputChip`/`SuggestionChip` with slot-based content, added `colors`/`elevation`/`border` props. Merged `FilterChip` into `Chip` module. ([#43900](https://github.com/expo/expo/pull/43900) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Refactored `Slider` to match native Material3 API: renamed `elementColors` to `colors`, removed `color` convenience prop. ([#43840](https://github.com/expo/expo/pull/43840) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] rename ContextMenu to DropdownMenu ([#43794](https://github.com/expo/expo/pull/43794) by [@Ubax](https://github.com/Ubax))
+- [android] configure ContextMenu by using native children ([#43792](https://github.com/expo/expo/pull/43792) by [@Ubax](https://github.com/Ubax))
+- [android] control ContextMenu expanded state from JS ([#43793](https://github.com/expo/expo/pull/43793) by [@Ubax](https://github.com/Ubax))
+- Bumped minimum iOS/tvOS version to 16.4, macOS to 13.4. ([#43296](https://github.com/expo/expo/pull/43296) by [@tsapeta](https://github.com/tsapeta))
+- [jetpack-compose] Changed `Host` underlying `MaterialTheme` to `MaterialExpressiveTheme`. ([#44896](https://github.com/expo/expo/pull/44896) by [@kudo](https://github.com/kudo))
+
 ### 🎉 New features
 
+- [android] Add `WorkletCallback` shared object for synchronous UI thread callbacks. ([#44681](https://github.com/expo/expo/pull/44681) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Add `ObservableState` shared object and `useNativeState` hook for controlling native Compose state from JS. ([#44655](https://github.com/expo/expo/pull/44655) by [@intergalacticspacehighway](https://github.com/intergalacticspacehighway))
+- [iOS] Added `Overlay` component. ([#44610](https://github.com/expo/expo/pull/44610) by [@nishan](https://github.com/intergalacticspacehighway))
+- add ExposedDropdownMenuBox ([#44201](https://github.com/expo/expo/pull/44201) by [@vonovak](https://github.com/vonovak))
+- Added `@expo/ui/community/segmented-control` — a drop-in replacement for `@react-native-segmented-control/segmented-control`. ([#44611](https://github.com/expo/expo/pull/44611) by [@vonovak](https://github.com/vonovak))
+- Added `@expo/ui/community/picker` — Android, iOS and web `Picker` drop-in replacement for `@react-native-picker/picker`. ([#44058](https://github.com/expo/expo/pull/44058) by [@vonovak](https://github.com/vonovak))
+- [iOS] Added `TabView` and `TabView.Tab` components wrapping SwiftUI's `TabView`, with `tabViewStyle` and `indexViewStyle` modifiers for the page (swipeable) and bottom-tab styles. ([#44780](https://github.com/expo/expo/pull/44780) by [@vonovak](https://github.com/vonovak))
+- [iOS] Added `containerRelativeShape` to shape types for `clipShape`, `mask`, `background`, `containerShape`, `contentShape`, and `glassEffect` modifiers. Enables proper shape adaptation in widgets and container-relative contexts using SwiftUI's `ContainerRelativeShape`. ([#44704](https://github.com/expo/expo/pull/44704) by [@hypnokermit](https://github.com/hypnokermit))
+- [iOS] Add `ObservableState` shared object and `useNativeState` hook for controlling native SwiftUI state from JS. ([#44214](https://github.com/expo/expo/pull/44214) by [@nishan](https://github.com/intergalacticspacehighway))
+- [iOS] Add shared object worklet support with `.value` property API for `ObservableState`. ([#44215](https://github.com/expo/expo/pull/44215) by [@nishan](https://github.com/intergalacticspacehighway))
+- [iOS] Add `WorkletCallback` shared object for synchronous UI thread callbacks. ([#44216](https://github.com/expo/expo/pull/44216) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Added `TooltipBox`, `PlainTooltip`, and `RichTooltip` components matching native Compose Tooltip API. Supports plain and rich tooltips with slot-based content, programmatic show/dismiss via ref, and `isPersistent`, `hasAction`, `enableUserInput`, `focusable` props. ([#44373](https://github.com/expo/expo/pull/44373) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Added `Badge` and `BadgedBox` components wrapping Jetpack Compose's Badge API for status indicators and count overlays. ([#44139](https://github.com/expo/expo/pull/44139) by [@benjaminkomen](https://github.com/benjaminkomen))
+- [android] Added `shape`, `border`, `selected`, `checked`, `onClick`, and `onCheckedChange` props to `Surface`, supporting clickable, selectable, and toggleable variants. ([#44079](https://github.com/expo/expo/pull/44079) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Added nested text support for Compose `Text` with style inheritance, custom fonts via `expo-font`, `background`, `shadow`, and `lineBreak` properties. ([#44094](https://github.com/expo/expo/pull/44094) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] Added `outlined` variant to `TextInput` component. ([#43719](https://github.com/expo/expo/pull/43719) by [@benjaminkomen](https://github.com/benjaminkomen))
+- Added `@expo/ui/datetimepicker` — an Android and iOS `DateTimePicker` drop-in replacement for `@react-native-community/datetimepicker`. ([#44014](https://github.com/expo/expo/pull/44014) by [@vonovak](https://github.com/vonovak))
+- [iOS] Added `locale` and `timeZone` support to `modifiers`. ([#44013](https://github.com/expo/expo/pull/44013) by [@vonovak](https://github.com/vonovak))
+- [android] Added `ref.hide()` for animated dismiss and more configurable props (`containerColor`, `contentColor`, `scrimColor`, `showDragHandle`, `sheetGesturesEnabled`, `properties`, `DragHandle` slot) to `BottomSheet`. ([#43972](https://github.com/expo/expo/pull/43972) by [@nishan](https://github.com/intergalacticspacehighway))
+- [iOS] Added `date`, `dateStyle`, `timerInterval`, `countsDown`, and `pauseTime` props to `Text` component for displaying auto-updating dates, timers, and countdowns using SwiftUI's `Text.DateStyle`. ([#43552](https://github.com/expo/expo/pull/43552) by [@LouisRaverdy](https://github.com/LouisRaverdy))
+- [android] Added `Checkbox` and `TriStateCheckbox` components. ([#43887](https://github.com/expo/expo/pull/43887) by [@nishan](https://github.com/intergalacticspacehighway))
+- [Android] Added `DatePickerDialog` and `TimePickerDialog` components, and `selectableDates` prop to `DateTimePicker`. ([#43895](https://github.com/expo/expo/pull/43895) by [@vonovak](https://github.com/vonovak))
+- [android] Added `FloatingActionButton` component. ([#43738](https://github.com/expo/expo/pull/43738) by [@benjaminkomen](https://github.com/benjaminkomen))
+- [android] Added `enabled`, `onValueChangeFinished`, and `Slider.Thumb`/`Slider.Track` slot support to `Slider` component. ([#43840](https://github.com/expo/expo/pull/43840) by [@nishan](https://github.com/intergalacticspacehighway))
+- [Android] Added `graphicsLayer` modifier and animation helpers for per-value animation in it. Added `indication` option to `clickable` modifier to control ripple effects. ([#43655](https://github.com/expo/expo/pull/43655) by [@vonovak](https://github.com/vonovak))
+- [Android] Added border color customization for `Switch` and `Checkbox` components. ([#43770](https://github.com/expo/expo/pull/43770) by [@liestig](https://github.com/liestig))
+- [iOS] Added `defaultScrollAnchor` modifier for controlling initial scroll position (iOS 17+). ([#43914](https://github.com/expo/expo/pull/43914) by [@ramonclaudio](https://github.com/ramonclaudio))
+- [iOS] Added `defaultScrollAnchorForRole` modifier for per-role scroll anchor control (iOS 18+). ([#43923](https://github.com/expo/expo/pull/43923) by [@ramonclaudio](https://github.com/ramonclaudio))
+- [iOS] Added `scrollTargetBehavior` and `scrollTargetLayout` modifiers for scroll target configuration (iOS 17+). ([#43955](https://github.com/expo/expo/pull/43955) by [@ramonclaudio](https://github.com/ramonclaudio))
+- [iOS] Added `textInputAutocapitalization` modifier for controlling keyboard autocapitalization behavior (iOS 15+). ([#44547](https://github.com/expo/expo/pull/44547) by [@ramonclaudio](https://github.com/ramonclaudio))
+- [iOS] Added `textContentType` modifier for enabling autofill and semantic text input hints (iOS 13+). ([#44548](https://github.com/expo/expo/pull/44548) by [@ramonclaudio](https://github.com/ramonclaudio))
+- [iOS] Added `rotation3DEffect` modifier for 3D rotation transforms ([#43640](https://github.com/expo/expo/pull/43640) by [@vonovak](https://github.com/vonovak))
+- [iOS] Added `ControlGroup` component. ([#43581](https://github.com/expo/expo/pull/43581) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] detect FAB in HorizontalFloatingToolbar ([#43601](https://github.com/expo/expo/pull/43601) by [@Ubax](https://github.com/Ubax))
+- [android] Add `elementColors` prop to the `DateTimePicker` component ([#43787](https://github.com/expo/expo/pull/43787) by [@iankberry](https://github.com/iankberry))
+- [iOS] Added `AccessoryWidgetBackground` component ([#43729](https://github.com/expo/expo/pull/43729) by [@huextrat](https://github.com/huextrat))
+- [iOS] Add support for local image uri ([#43707](https://github.com/expo/expo/pull/43707) by [@jakex7](https://github.com/jakex7))
+- [android] add AnimatedVisibility transition API ([#43632](https://github.com/expo/expo/pull/43632) by [@Ubax](https://github.com/Ubax))
+- [android] add `imePadding` modifier ([#43652](https://github.com/expo/expo/pull/43652) by [@Ubax](https://github.com/Ubax))
+- [iOS] Add `Link` view. ([#43983](https://github.com/expo/expo/pull/43983) by [@jakex7](https://github.com/jakex7))
+- [iOS] Add `widgetURL` modifier. ([#43984](https://github.com/expo/expo/pull/43984) by [@jakex7](https://github.com/jakex7))
+- [swift-ui] Added `LazyHStack` and `LazyVStack`. ([#44612](https://github.com/expo/expo/pull/44612) by [@kudo](https://github.com/kudo))
+- [jetpack-compose] Added `LazyRow` component and `onVisibilityChanged` modifier. ([#44615](https://github.com/expo/expo/pull/44615) by [@kudo](https://github.com/kudo))
+- Added universal components. ([#44601](https://github.com/expo/expo/pull/44601) by [@kudo](https://github.com/kudo))
+- [iOS] Add `containerBackground` modifier. ([#44192](https://github.com/expo/expo/pull/44192) by [@jakex7](https://github.com/jakex7))
+- [jetpack-compose] Added `defaultMinSize` modifier. ([#44813](https://github.com/expo/expo/pull/44813) by [@kudo](https://github.com/kudo))
+- [jetpack-compose] Added Material 3 dynamic colors support. ([#44896](https://github.com/expo/expo/pull/44896) by [@kudo](https://github.com/kudo))
+- Added universal `FieldGroup` and `Spacer`. ([#44814](https://github.com/expo/expo/pull/44814) by [@kudo](https://github.com/kudo))
+
 ### 🐛 Bug fixes
 
+- Fix `installOnUIRuntime` crash by ensuring `react-native-reanimated` initializes before accessing worklet runtime. ([#44582](https://github.com/expo/expo/pull/44582) by [@intergalacticspacehighway](https://github.com/intergalacticspacehighway))
+- [iOS] Fix initial prop values not being applied since `init` runs before `updateProps`. ([#43954](https://github.com/expo/expo/pull/43954) by [@nishan](https://github.com/intergalacticspacehighway))
+- [iOS] Fix prop syncing race condition where stale values override user interactions. Replace `onReceive(Sequence.publisher)` with `onAppear` + `onChange` across all SwiftUI views. ([#43954](https://github.com/expo/expo/pull/43954) by [@nishan](https://github.com/intergalacticspacehighway))
+- [iOS] Fix `Slider` thumb snapping back during drag by guarding `.onReceive` with `isEditing` state. ([#43701](https://github.com/expo/expo/issues/43701) by [@fedeciancaglini](https://github.com/fedeciancaglini)) ([#43797](https://github.com/expo/expo/pull/43797) by [@fedeciancaglini](https://github.com/fedeciancaglini))
+- [Android] Fix touch events for RN views inside Compose BottomSheet. ([#43716](https://github.com/expo/expo/pull/43716) by [@nishan](https://github.com/intergalacticspacehighway))
+- [Android] Fix `RNHostView` child parent related crash. ([#43691](https://github.com/expo/expo/pull/43691) by [@nishan](https://github.com/intergalacticspacehighway))
+- [iOS] Fix `foregroundStyle` typings and runtime narrowing so React Native color values like `PlatformColor()` work in color and gradient styles. ([#44349](https://github.com/expo/expo/pull/44349) by [@eliotgevers](https://github.com/eliotgevers))
+- [Android] Added `RNHostView` to improve RN component layout inside Compose views. ([#43495](https://github.com/expo/expo/pull/43495) by [@nishan](https://github.com/intergalacticspacehighway))
+- [Android] Fix `ContextMenu` not expanding when triggered by `IconButton`. ([#43592](https://github.com/expo/expo/pull/43592) by [@nishan](https://github.com/intergalacticspacehighway))
+- [android] fix modifiers export ([#43639](https://github.com/expo/expo/pull/43639) by [@Ubax](https://github.com/Ubax))
+- [jetpack-compose] Fixed `RNHostView` re-parenting exception. ([#44522](https://github.com/expo/expo/pull/44522) by [@kudo](https://github.com/kudo))
+- Fixed runtime crash when missing `Host` component for SwiftUI or Jetpack Compose components. ([#44118](https://github.com/expo/expo/pull/44118) by [@kudo](https://github.com/kudo))
+
 ### 💡 Others
 
+- [iOS] Add `AsyncFunction` support in `ExpoUIView` definition function. ([#43669](https://github.com/expo/expo/pull/43669) by [@nishan](https://github.com/intergalacticspacehighway))
+- [iOS] Introduce `SlotView` to replace structural child view types with a single generic slot. ([#43607](https://github.com/expo/expo/pull/43607) by [@nishan](https://github.com/intergalacticspacehighway))
+- [iOS] Make RNHostView SwiftUI view ([#43570](https://github.com/expo/expo/pull/43570) by [@nishan](https://github.com/intergalacticspacehighway))
+- [jetpack-compose] Use view hash code as key for `Children`. ([#44521](https://github.com/expo/expo/pull/44521) by [@kudo](https://github.com/kudo))
+- Refactored `ComposableScope` and allow extensibility. ([#44698](https://github.com/expo/expo/pull/44698) by [@kudo](https://github.com/kudo))
+- [jetpack-compose] Reuse `HorizontalAlignment` converter in `LazyColumn`. ([#44755](https://github.com/expo/expo/pull/44755) by [@kudo](https://github.com/kudo))
+- [jetpack-compose] Added `horizontalScroll` and `verticalScroll` modifiers. ([#44464](https://github.com/expo/expo/pull/44464) by [@kudo](https://github.com/kudo))
+- [Android] Added AsyncFunction support to the functional `ExpoUIView` DSL. ([#44081](https://github.com/expo/expo/pull/44081) by [@kudo](https://github.com/kudo))
+- [iOS] Fixed build error when using precompiled `ExpoModulesCore.xcframework`. ([#45016](https://github.com/expo/expo/pull/45016) by [@kudo](https://github.com/kudo))
+- [Android] Improved application startup performance by reducing reflection. ([#45021](https://github.com/expo/expo/pull/45021) by [@lukmccall](https://github.com/lukmccall))
+
+## 55.0.1 — 2026-02-25
+
+### 🎉 New features
+
+- [iOS] Added `luminanceToAlpha` modifier. ([#43417](https://github.com/expo/expo/pull/43417) by [@jakex7](https://github.com/jakex7))
+
 ## 55.0.0 — 2026-02-25
 
 ### 🎉 New features
@@ -163,6 +265,7 @@ _This version does not introduce any user-facing changes._
 
 ### 🎉 New features
 
+- [Android] Add `label`, and `placeholder` props to TextField component. ([#40452](https://github.com/expo/expo/pull/40452) by [@akshayjadhav4](https://github.com/akshayjadhav4))
 - [iOS] Add `refreshable` modifier. ([#40201](https://github.com/expo/expo/pull/40201) by [@christianwooldridge](https://github.com/christianwooldridge))
 - [iOS] Add RTL support in swiftui. ([#40335](https://github.com/expo/expo/pull/40335) by [@kfirfitousi](https://github.com/kfirfitousi))
 - [Android] Add Carousel component. ([#40325](https://github.com/expo/expo/pull/40325) by [@aleqsio](https://github.com/aleqsio))

package/CLAUDE.md

@@ -0,0 +1,54 @@
+# expo-ui component guidelines
+
+expo-ui is a library of native UI components for React Native, bridging SwiftUI views on iOS and Jetpack Compose components on Android. Each platform has its own set of components exported from `@expo/ui/swift-ui` and `@expo/ui/jetpack-compose` respectively.
+
+## Core principle
+
+Bridge native components to JavaScript with as little abstraction as possible. Native views should be thin wrappers — no added logic, state management, or behavior beyond what the platform component provides. Everything that can be set or controlled from JavaScript should be controlled from JavaScript.
+
+Prefer controlled components: state lives in JS and is passed as props, not managed internally by the native view. Use a prop + callback pattern (e.g. `page` + `onPageChange`) instead of imperative ref methods (e.g. `setPage(index)`). This keeps the source of truth in React and makes components predictable and composable.
+
+## Naming
+
+- The JavaScript API must mirror the native APIs closely.
+- Exported components must have the same name as the underlying native component (e.g. SwiftUI `TabView` -> export `TabView`, Jetpack Compose `HorizontalPager` -> export `HorizontalPager`).
+- Don't turn native-layer modifiers into props in the JS layer — modifiers stay as modifiers.
+- Use `export function ComponentName` (the dominant pattern in this codebase). Use `export const` only for non-component values like modifiers or constants. Avoid the `export { LocalName as ExportName }` rename pattern unless the local name must differ.
+- Props, constants, and enum values must use the same names as the native API. If SwiftUI calls it `scrollEnabled`, the JS prop is `scrollEnabled`. If Compose calls it `userScrollEnabled`, the JS prop is `userScrollEnabled`.
+- Ensure components have the correct display name in React DevTools. Either name the function directly (e.g. `function TabView`) or set `.displayName`.
+
+## Props and events
+
+- Include JSDoc for every supported prop.
+- Events follow the expo-ui `ViewEvent` pattern: the public JS callback receives unwrapped values (e.g. `onPageSelected?: (position: number) => void`), and the component internally adapts to/from the native event shape.
+
+## Native code
+
+- Expose all configurable properties of the underlying native component as props. Don't hardcode values that the user might want to change.
+- Use `@Field` (iOS) and data class fields (Android) for props, `EventDispatcher` for events, and `AsyncFunction` for imperative methods when unavoidable.
+
+## File structure
+
+- iOS (SwiftUI): `packages/expo-ui/ios/<ComponentName>/<ComponentName>View.swift` (or `ios/<ComponentName>View.swift` for simple components)
+- Android (Compose): `packages/expo-ui/android/src/main/java/expo/modules/ui/<ComponentName>View.kt`
+- TypeScript (SwiftUI): `packages/expo-ui/src/swift-ui/<ComponentName>/index.tsx`
+- TypeScript (Compose): `packages/expo-ui/src/jetpack-compose/<ComponentName>/index.tsx`
+- Register views in `ios/ExpoUIModule.swift` and `android/.../ExpoUIModule.kt`
+- Export from `src/swift-ui/index.tsx` and `src/jetpack-compose/index.ts`
+
+## Example screens
+
+For every component added, create example screens in NCL (native-component-list):
+
+- `apps/native-component-list/src/screens/UI/<ComponentName>Screen.ios.tsx` — imports from `@expo/ui/swift-ui`
+- `apps/native-component-list/src/screens/UI/<ComponentName>Screen.android.tsx` — imports from `@expo/ui/jetpack-compose`
+- Register in both `UIScreen.ios.tsx` and `UIScreen.android.tsx`
+- Keep the minimum set of examples needed to cover available features.
+
+## Before committing
+
+1. Run `pnpm build` in the package directory — the `build/` output must be committed alongside source changes. CI will fail otherwise.
+2. Run `pnpm lint --max-warnings 0`.
+3. Add a changelog entry to `CHANGELOG.md` under the "Unpublished" section.
+4. When adding a new component, add documentation for it. When adding a new feature to an existing component, update its documentation accordingly. Docs are MDX files in `docs/pages/versions/unversioned/sdk/ui/swift-ui/` and `docs/pages/versions/unversioned/sdk/ui/jetpack-compose/`.
+5. Regenerate API docs data by running `et gdad -p @expo/ui`. If the change is to be cherry-picked to an already-released SDK version, also run `et gdad -p @expo/ui -s <version>` (e.g. `et gdad -p @expo/ui -s 55` for SDK 55). Changes are very likely to be picked to the latest stable of expo-ui (`npm view @expo/ui version`).

package/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing to `@expo/ui`
+
+`@expo/ui` maps native UI frameworks (SwiftUI on iOS, Jetpack Compose on Android) to React Native.
+
+## Before opening a PR
+
+- [ ] Rebuilt JS output: `yarn build` (from `packages/expo-ui/`) and committed the `build/` output.
+
+### When adding or updating a component
+
+- [ ] Added an example to the relevant screen in `apps/native-component-list/src/screens/UI/`
+- [ ] Regenerated docs (from repo root): `et gdad -p "expo-ui/swift-ui/<component>"` and/or `et gdad -p "expo-ui/jetpack-compose/<component>"`
+- [ ] Added an example in the relevant docs page
+
+### When adding or updating a modifier
+
+- [ ] Added an example to the relevant screen in `apps/native-component-list/src/screens/UI/`
+- [ ] Regenerated docs (from repo root): `et gdad -p "expo-ui/swift-ui/modifiers"` and/or `et gdad -p "expo-ui/jetpack-compose/modifiers"`
+
+## Project structure
+
+- `packages/expo-ui/ios/` - Swift/SwiftUI source files
+- `packages/expo-ui/android/` - Kotlin/Jetpack Compose source files
+- `packages/expo-ui/src/swift-ui/` - TypeScript components and types for the SwiftUI side
+- `packages/expo-ui/src/jetpack-compose/` - TypeScript components and types for the Compose side
+
+## General guidelines
+
+- **Match the native APIs** — prop names, types, and behavior should mirror their SwiftUI / Jetpack Compose counterparts as closely as possible.
+- **Reuse existing types** — before creating a new Record or TypeScript type, check if one already exists.

package/android/build.gradle

@@ -12,13 +12,13 @@ apply plugin: 'expo-module-gradle-plugin'
 apply plugin: 'org.jetbrains.kotlin.plugin.compose'
 
 group = 'expo.modules.ui'
-version = '55.0.0'
+version = '55.0.2-canary-20260424-7bedc9d'
 
 android {
   namespace "expo.modules.ui"
   defaultConfig {
     versionCode 1
-    versionName "55.0.0"
+    versionName "55.0.2-canary-20260424-7bedc9d"
     testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
   }
   buildFeatures {
@@ -37,15 +37,16 @@ android {
 dependencies {
   implementation 'com.facebook.react:react-android'
 
-  implementation 'androidx.compose.foundation:foundation-android:1.10.2'
-  implementation 'androidx.compose.ui:ui-android:1.10.2'
-  implementation "androidx.compose.material3:material3:1.5.0-alpha13"
-  implementation 'androidx.compose.material3:material3-android:1.5.0-alpha13'
+  implementation 'androidx.compose.foundation:foundation-android:1.10.6'
+  implementation 'androidx.compose.ui:ui-android:1.10.6'
+  implementation "androidx.compose.material3:material3:1.5.0-alpha17"
+  implementation 'androidx.compose.material3:material3-android:1.5.0-alpha17'
   implementation 'androidx.lifecycle:lifecycle-runtime:2.10.0'
   implementation 'androidx.fragment:fragment-ktx:1.8.9'
   implementation "androidx.graphics:graphics-shapes:1.1.0"
   implementation "com.squareup.okhttp3:okhttp:4.9.2"
-  implementation "androidx.core:core-ktx:1.17.0"
+  implementation "com.google.android.material:material:1.13.0"
+  implementation "androidx.core:core-ktx:1.18.0"
 
   // Testing
   testImplementation 'junit:junit:4.13.2'

package/android/src/main/java/expo/modules/ui/AlertDialogView.kt

@@ -1,52 +1,85 @@
 package expo.modules.ui
 
+import android.graphics.Color
 import androidx.compose.material3.AlertDialog
-import androidx.compose.material3.Text
-import androidx.compose.material3.TextButton
+import androidx.compose.material3.AlertDialogDefaults
 import androidx.compose.runtime.Composable
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.window.DialogProperties
+import expo.modules.kotlin.records.Field
 import expo.modules.kotlin.records.Record
 import expo.modules.kotlin.views.ComposeProps
 import expo.modules.kotlin.views.FunctionalComposableScope
-import java.io.Serializable
+import expo.modules.kotlin.types.OptimizedRecord
+import expo.modules.kotlin.views.OptimizedComposeProps
 
-open class AlertDialogButtonPressedEvent() : Record, Serializable
+@OptimizedRecord
+data class AlertDialogColors(
+  @Field val containerColor: Color? = null,
+  @Field val iconContentColor: Color? = null,
+  @Field val titleContentColor: Color? = null,
+  @Field val textContentColor: Color? = null
+) : Record
 
+@OptimizedRecord
+data class ExpoDialogProperties(
+  @Field val dismissOnBackPress: Boolean = true,
+  @Field val dismissOnClickOutside: Boolean = true,
+  @Field val usePlatformDefaultWidth: Boolean = true,
+  @Field val decorFitsSystemWindows: Boolean = true
+) : Record
+
+@OptimizedComposeProps
 data class AlertDialogProps(
-  val title: String? = null,
-  val text: String? = null,
-  val confirmButtonText: String? = null,
-  val dismissButtonText: String? = null,
-  val visible: Boolean = false,
+  val colors: AlertDialogColors = AlertDialogColors(),
+  val tonalElevation: Double? = null,
+  val properties: ExpoDialogProperties = ExpoDialogProperties(),
   val modifiers: ModifierList = emptyList()
 ) : ComposeProps
 
 @Composable
 fun FunctionalComposableScope.AlertDialogContent(
   props: AlertDialogProps,
-  onDismissPressed: (AlertDialogButtonPressedEvent) -> Unit,
-  onConfirmPressed: (AlertDialogButtonPressedEvent) -> Unit
+  onDismissRequest: () -> Unit
 ) {
-  if (!props.visible) {
-    return
-  }
+  val titleSlotView = findChildSlotView(view, "title")
+  val textSlotView = findChildSlotView(view, "text")
+  val confirmButtonSlotView = findChildSlotView(view, "confirmButton")
+  val dismissButtonSlotView = findChildSlotView(view, "dismissButton")
+  val iconSlotView = findChildSlotView(view, "icon")
 
   AlertDialog(
+    onDismissRequest = { onDismissRequest() },
     confirmButton = {
-      props.confirmButtonText?.let {
-        TextButton(onClick = { onConfirmPressed(AlertDialogButtonPressedEvent()) }) {
-          Text(it)
-        }
-      }
+      confirmButtonSlotView?.renderSlot()
+    },
+    modifier = ModifierRegistry.applyModifiers(props.modifiers, appContext, composableScope, globalEventDispatcher),
+    dismissButton = dismissButtonSlotView?.let {
+      { it.renderSlot() }
+    },
+    title = titleSlotView?.let {
+      { it.renderSlot() }
+    },
+    text = textSlotView?.let {
+      { it.renderSlot() }
     },
-    dismissButton = {
-      props.dismissButtonText?.let {
-        TextButton(onClick = { onDismissPressed(AlertDialogButtonPressedEvent()) }) {
-          Text(it)
-        }
-      }
+    icon = iconSlotView?.let {
+      { it.renderSlot() }
     },
-    onDismissRequest = { onDismissPressed(AlertDialogButtonPressedEvent()) },
-    title = { props.title?.let { Text(it) } },
-    text = { props.text?.let { Text(it) } }
+    containerColor = props.colors.containerColor.composeOrNull
+      ?: AlertDialogDefaults.containerColor,
+    iconContentColor = props.colors.iconContentColor.composeOrNull
+      ?: AlertDialogDefaults.iconContentColor,
+    titleContentColor = props.colors.titleContentColor.composeOrNull
+      ?: AlertDialogDefaults.titleContentColor,
+    textContentColor = props.colors.textContentColor.composeOrNull
+      ?: AlertDialogDefaults.textContentColor,
+    tonalElevation = props.tonalElevation?.dp ?: AlertDialogDefaults.TonalElevation,
+    properties = DialogProperties(
+      dismissOnBackPress = props.properties.dismissOnBackPress,
+      dismissOnClickOutside = props.properties.dismissOnClickOutside,
+      usePlatformDefaultWidth = props.properties.usePlatformDefaultWidth,
+      decorFitsSystemWindows = props.properties.decorFitsSystemWindows
+    )
   )
 }

package/android/src/main/java/expo/modules/ui/AnimatedVisibilityView.kt

@@ -0,0 +1,134 @@
+package expo.modules.ui
+
+import androidx.compose.animation.AnimatedVisibility
+import androidx.compose.animation.EnterTransition
+import androidx.compose.animation.ExitTransition
+import androidx.compose.animation.expandHorizontally
+import androidx.compose.animation.expandIn
+import androidx.compose.animation.expandVertically
+import androidx.compose.animation.fadeIn
+import androidx.compose.animation.fadeOut
+import androidx.compose.animation.scaleIn
+import androidx.compose.animation.scaleOut
+import androidx.compose.animation.shrinkHorizontally
+import androidx.compose.animation.shrinkOut
+import androidx.compose.animation.shrinkVertically
+import androidx.compose.animation.slideInHorizontally
+import androidx.compose.animation.slideInVertically
+import androidx.compose.animation.slideOutHorizontally
+import androidx.compose.animation.slideOutVertically
+import androidx.compose.runtime.Composable
+import expo.modules.kotlin.records.Field
+import expo.modules.kotlin.records.Record
+import expo.modules.kotlin.types.Enumerable
+import expo.modules.kotlin.views.ComposeProps
+import expo.modules.kotlin.views.FunctionalComposableScope
+import expo.modules.kotlin.types.OptimizedRecord
+import expo.modules.kotlin.views.OptimizedComposeProps
+
+// region Transition types
+
+enum class EnterTransitionType(val value: String) : Enumerable {
+  FADE_IN("fadeIn"),
+  SLIDE_IN_HORIZONTALLY("slideInHorizontally"),
+  SLIDE_IN_VERTICALLY("slideInVertically"),
+  EXPAND_IN("expandIn"),
+  EXPAND_HORIZONTALLY("expandHorizontally"),
+  EXPAND_VERTICALLY("expandVertically"),
+  SCALE_IN("scaleIn")
+}
+
+enum class ExitTransitionType(val value: String) : Enumerable {
+  FADE_OUT("fadeOut"),
+  SLIDE_OUT_HORIZONTALLY("slideOutHorizontally"),
+  SLIDE_OUT_VERTICALLY("slideOutVertically"),
+  SHRINK_OUT("shrinkOut"),
+  SHRINK_HORIZONTALLY("shrinkHorizontally"),
+  SHRINK_VERTICALLY("shrinkVertically"),
+  SCALE_OUT("scaleOut")
+}
+
+@OptimizedRecord
+data class EnterTransitionRecord(
+  @Field val type: EnterTransitionType = EnterTransitionType.FADE_IN,
+  @Field val initialAlpha: Float? = null,
+  @Field val initialOffsetX: Float? = null,
+  @Field val initialOffsetY: Float? = null,
+  @Field val initialScale: Float? = null
+) : Record
+
+@OptimizedRecord
+data class ExitTransitionRecord(
+  @Field val type: ExitTransitionType = ExitTransitionType.FADE_OUT,
+  @Field val targetAlpha: Float? = null,
+  @Field val targetOffsetX: Float? = null,
+  @Field val targetOffsetY: Float? = null,
+  @Field val targetScale: Float? = null
+) : Record
+
+// endregion
+
+// region Transition conversion
+
+// TODO(@ubax): expose animationSpec parameter (tween, spring, duration) for all transitions
+private fun EnterTransitionRecord.toComposeTransition(): EnterTransition = when (type) {
+  EnterTransitionType.FADE_IN ->
+    if (initialAlpha != null) fadeIn(initialAlpha = initialAlpha) else fadeIn()
+  EnterTransitionType.SLIDE_IN_HORIZONTALLY ->
+    if (initialOffsetX != null) slideInHorizontally { (it * initialOffsetX).toInt() } else slideInHorizontally()
+  EnterTransitionType.SLIDE_IN_VERTICALLY ->
+    if (initialOffsetY != null) slideInVertically { (it * initialOffsetY).toInt() } else slideInVertically()
+  // TODO(@ubax): expose expandFrom (Alignment) and initialSize parameters for expand transitions
+  EnterTransitionType.EXPAND_IN -> expandIn()
+  EnterTransitionType.EXPAND_HORIZONTALLY -> expandHorizontally()
+  EnterTransitionType.EXPAND_VERTICALLY -> expandVertically()
+  EnterTransitionType.SCALE_IN ->
+    if (initialScale != null) scaleIn(initialScale = initialScale) else scaleIn()
+}
+
+private fun ExitTransitionRecord.toComposeTransition(): ExitTransition = when (type) {
+  ExitTransitionType.FADE_OUT ->
+    if (targetAlpha != null) fadeOut(targetAlpha = targetAlpha) else fadeOut()
+  ExitTransitionType.SLIDE_OUT_HORIZONTALLY ->
+    if (targetOffsetX != null) slideOutHorizontally { (it * targetOffsetX).toInt() } else slideOutHorizontally()
+  ExitTransitionType.SLIDE_OUT_VERTICALLY ->
+    if (targetOffsetY != null) slideOutVertically { (it * targetOffsetY).toInt() } else slideOutVertically()
+  // TODO(@ubax): expose shrinkTowards (Alignment) and targetSize parameters for shrink transitions
+  ExitTransitionType.SHRINK_OUT -> shrinkOut()
+  ExitTransitionType.SHRINK_HORIZONTALLY -> shrinkHorizontally()
+  ExitTransitionType.SHRINK_VERTICALLY -> shrinkVertically()
+  ExitTransitionType.SCALE_OUT ->
+    if (targetScale != null) scaleOut(targetScale = targetScale) else scaleOut()
+}
+
+private fun List<EnterTransitionRecord>.toComposedEnterTransition(): EnterTransition? =
+  map { it.toComposeTransition() }.reduceOrNull { acc, transition -> acc + transition }
+
+private fun List<ExitTransitionRecord>.toComposedExitTransition(): ExitTransition? =
+  map { it.toComposeTransition() }.reduceOrNull { acc, transition -> acc + transition }
+
+// endregion
+
+@OptimizedComposeProps
+data class AnimatedVisibilityProps(
+  val visible: Boolean = true,
+  val enterTransition: List<EnterTransitionRecord>? = null,
+  val exitTransition: List<ExitTransitionRecord>? = null,
+  val modifiers: ModifierList = emptyList()
+) : ComposeProps
+
+@Composable
+fun FunctionalComposableScope.AnimatedVisibilityContent(props: AnimatedVisibilityProps) {
+  val enter = props.enterTransition?.takeIf { it.isNotEmpty() }?.toComposedEnterTransition()
+  val exit = props.exitTransition?.takeIf { it.isNotEmpty() }?.toComposedExitTransition()
+
+  AnimatedVisibility(
+    visible = props.visible,
+    enter = enter ?: (fadeIn() + expandIn()),
+    exit = exit ?: (fadeOut() + shrinkOut()),
+    modifier = ModifierRegistry
+      .applyModifiers(props.modifiers, appContext, composableScope, globalEventDispatcher)
+  ) {
+    Children(UIComposableScope())
+  }
+}

package/android/src/main/java/expo/modules/ui/BadgeView.kt

@@ -0,0 +1,75 @@
+package expo.modules.ui
+
+import android.graphics.Color
+import androidx.compose.foundation.layout.Box
+import androidx.compose.material3.Badge
+import androidx.compose.material3.BadgeDefaults
+import androidx.compose.material3.contentColorFor
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.layout.layout
+import androidx.compose.ui.unit.dp
+import androidx.core.view.size
+import expo.modules.kotlin.views.ComposeProps
+import expo.modules.kotlin.views.FunctionalComposableScope
+import expo.modules.kotlin.views.OptimizedComposeProps
+
+@OptimizedComposeProps
+data class BadgeProps(
+  val containerColor: Color? = null,
+  val contentColor: Color? = null,
+  val modifiers: ModifierList = emptyList()
+) : ComposeProps
+
+@Composable
+fun FunctionalComposableScope.BadgeContent(props: BadgeProps) {
+  val resolvedContainerColor = props.containerColor.composeOrNull ?: BadgeDefaults.containerColor
+  val modifier = ModifierRegistry.applyModifiers(props.modifiers, appContext, composableScope, globalEventDispatcher)
+
+  if (view.size > 0) {
+    Badge(
+      modifier = modifier,
+      containerColor = resolvedContainerColor,
+      contentColor = props.contentColor.composeOrNull ?: contentColorFor(resolvedContainerColor)
+    ) {
+      Box(
+        modifier = Modifier.ensureBadgeContentCircular(),
+        contentAlignment = Alignment.Center
+      ) {
+        Children(UIComposableScope())
+      }
+    }
+  } else {
+    // No content lambda → renders as small 6dp dot per M3 spec
+    Badge(
+      modifier = modifier,
+      containerColor = resolvedContainerColor
+    )
+  }
+}
+
+/**
+ * Layout modifier that sizes the Badge content so the Badge renders as a circle
+ * for narrow content (single digits). Badge internally adds 4dp horizontal padding
+ * on each side (8dp total) but no vertical padding. To make the Badge square
+ * (and thus circular with CornerFull shape), the content width must be
+ * `height - totalHorizontalPadding`. For wide content (e.g. "999+"), the natural
+ * width is used, producing a pill shape.
+ *
+ * This is a workaround for Compose Badge becoming oval at font scales > 1.0.
+ * @see: https://issuetracker.google.com/issues/365493087
+ */
+private fun Modifier.ensureBadgeContentCircular() = layout { measurable, constraints ->
+  val placeable = measurable.measure(constraints)
+  // Badge adds 4dp padding on each side = 8dp total horizontal padding
+  val targetWidth = placeable.height - BadgeHorizontalPaddingTotal.roundToPx()
+  val width = maxOf(placeable.width, targetWidth)
+  layout(width, placeable.height) {
+    placeable.placeRelative((width - placeable.width) / 2, 0)
+  }
+}
+
+// Badge internal horizontal padding: 4dp per side = 8dp total
+// (BadgeWithContentHorizontalPadding is internal in Material 3)
+private val BadgeHorizontalPaddingTotal = 8.dp

package/android/src/main/java/expo/modules/ui/BadgedBoxView.kt

@@ -0,0 +1,25 @@
+package expo.modules.ui
+
+import androidx.compose.material3.Badge
+import androidx.compose.material3.BadgedBox
+import androidx.compose.runtime.Composable
+import expo.modules.kotlin.views.ComposeProps
+import expo.modules.kotlin.views.FunctionalComposableScope
+import expo.modules.kotlin.views.OptimizedComposeProps
+
+@OptimizedComposeProps
+data class BadgedBoxProps(
+  val modifiers: ModifierList = emptyList()
+) : ComposeProps
+
+@Composable
+fun FunctionalComposableScope.BadgedBoxContent(props: BadgedBoxProps) {
+  val badgeSlot = findChildSlotView(view, "badge")
+
+  BadgedBox(
+    badge = { badgeSlot?.renderSlot() ?: Badge() },
+    modifier = ModifierRegistry.applyModifiers(props.modifiers, appContext, composableScope, globalEventDispatcher)
+  ) {
+    Children(UIComposableScope()) { !isSlotView(it) }
+  }
+}