poppo

While Tooltip and Popover share a similar structure, they serve different purposes and behave differently regarding user interaction and accessibility:

Best Practice: Always put buttons inside a Popover, never a Tooltip.

Both Tooltip and Popover share the same component anatomy. They use a compound component pattern where the Root component manages the state and reads configuration from its children.

Important: Do not wrap the sub-components (like Positioner or Popup) in your own custom components. Root uses React context/composition to find these elements, and custom wrappers can prevent Root from detecting them.

Anatomy:

• <Root>: Manages the open state.
• <Trigger />: The element that initiates the popup (via hover or press).
• <Portal>: Renders the content outside the parent hierarchy (to avoid clipping).
• <Positioner>: Controls positioning via side and sideOffset.
• <Popup>: The actual content bubble.
• <Arrow />: The directional pointer for the bubble.

Toasts follow a provider-based architecture designed for mobile notifications.

The Hierarchy:

1. <Toast.Provider>: The central manager. It accepts configuration for timeout, limit (max visible toasts), and overflow (how to handle new toasts when the limit is reached, e.g., replace or queue).
2. <Toast.Viewport>: The visual container where toasts are stacked. It accepts position and insets (for safe areas).
3. <Toast.Root>: Represents a single toast instance. It provides built-in support for enter/exit animations, swipe-to-dismiss gestures, and pausing the auto-dismiss timer when the user is touching the toast.
4. Toast Content: Inside Toast.Root, you compose the UI using <Toast.Title />, <Toast.Description />, <Toast.Action />, and <Toast.Close />.

The example/ directory contains a playground app used for testing. Use the following commands to run the test suite or the app:

yarn test      # Run toast manager schedule tests (Jest)
cd example
yarn ios       # Run on iOS
yarn android    # Run on Android
yarn test:ios  # Run XCUITest suite (real touches against real popups)

Install the core package using Expo:

npx expo install poppo

Native Dependencies

Toasts require react-native-reanimated and react-native-gesture-handler. You must wrap your application root with GestureHandlerRootView:

import { GestureHandlerRootView } from "react-native-gesture-handler";

<GestureHandlerRootView style={{ flex: 1 }}>
  <App />
</GestureHandlerRootView>;

Web Dependency

For web support, you must also install @base-ui/react:

yarn add @base-ui/react

Note: Expo SDK 53+ handles native requirements (iOS 16.4+, Swift 5.9) automatically via autolinking.

npx expo install poppo
npx expo install react-native-reanimated react-native-gesture-handler
yarn add @base-ui/react

As of version 2.0, universal-tooltip has been renamed to poppo. The universal-tooltip package now only serves as a re-export of poppo to maintain backward compatibility. For new projects or to access the latest features and fixes, you should install and use poppo directly. The native module is included in poppo, and Expo autolinking will handle it as a dependency.

# Install the new package
yarn add poppo

- import { Tooltip } from "universal-tooltip";
+ import { Tooltip } from "poppo";

The ToastManager handles high volumes of toasts using two main mechanisms:

Overflow Strategies

When the limit of visible toasts is reached, the overflow setting determines what happens to new arrivals:

• queue (default): New toasts are placed in a queue and will only become visible once an existing toast is removed.
• replace: The oldest visible toast is immediately closed to make room for the new toast (similar to Android Snackbars).

Demotion

To prevent a long stack of toasts from staying visible for too long, the manager uses demotedTimeout. When a new toast arrives and becomes the front-most item, all other visible toasts are 'demoted'. Their remaining auto-dismiss time is capped at the demotedTimeout value. This ensures the stack clears more quickly when many toasts are triggered in rapid succession.

Wrap your application (or a specific part of it) in <Toast.Provider> to enable toast functionality. You can provide an external toastManager created via createToastManager(), or let the provider create its own internal manager with custom settings.

Key configuration options for the internal manager:

• timeout: Default auto-dismiss timeout in ms (default: 5000).
• limit: Maximum number of toasts visible at once (default: Infinity).
• overflow: Behavior when limit is reached. Options: 'queue' (shows when a slot frees up) or 'replace' (closes oldest visible toast to show new one).
• demotedTimeout: Ceiling in ms on how long a toast has left once pushed back in the stack (default: 2000).

import { Provider } from './toast';

<Provider 
  timeout={3000} 
  limit={3} 
  overflow="queue"
>
  <App />
</Provider>