### Install Reanimated and Gesture Handler
Source: https://github.com/alantoa/poppo/blob/main/README.md
Installs the required peer dependencies for poppo toasts.
```sh
npx expo install react-native-reanimated react-native-gesture-handler
```
--------------------------------
### Install poppo with npx expo install
Source: https://github.com/alantoa/poppo/blob/main/README.md
Installs the poppo library in an Expo project.
```sh
npx expo install poppo
```
--------------------------------
### Gradle build with ANDROID_HOME
Source: https://github.com/alantoa/poppo/blob/main/AGENTS.md
Build the Android example app. Requires ANDROID_HOME to be set, otherwise Gradle reports 'SDK location not found'.
```sh
cd example/android && ANDROID_HOME=$HOME/Library/Android/sdk ./gradlew :app:assembleDebug
```
--------------------------------
### Install Base UI for web
Source: https://github.com/alantoa/poppo/blob/main/README.md
Adds the Base UI peer dependency required for web support.
```sh
yarn add @base-ui/react
```
--------------------------------
### Install poppo with yarn
Source: https://github.com/alantoa/poppo/blob/main/alias/universal-tooltip/README.md
Install the renamed package using yarn. This replaces the old universal-tooltip dependency.
```sh
yarn add poppo
```
--------------------------------
### Run toast manager tests and example app
Source: https://github.com/alantoa/poppo/blob/main/README.md
Run the toast manager's Jest schedule with `yarn test`, then move into the `example/` playground app and launch it on iOS or Android with `yarn ios` or `yarn android`. Finally, run the XCUITest suite with `yarn test:ios` to perform real touches against real popups.
```sh
yarn test # the toast manager's schedule, under jest
cd example
yarn ios # or yarn android
yarn test:ios # XCUITest suite — real touches against real popups
```
--------------------------------
### Development commands for poppo
Source: https://github.com/alantoa/poppo/blob/main/AGENTS.md
Run lint, tests, type-check, build, and example app commands. yarn test uses plain ts-jest in a node environment and needs no mocks because it only imports src/toast-manager.ts. yarn build does not clean, so deleted source files linger in build/.
```sh
yarn lint # eslint (src only)
yarn test # jest: the toast manager's schedule (see below)
npx tsc --noEmit # library
npx tsc --noEmit -p example/tsconfig.json
yarn build # tsc to build/ + copy the css (does NOT clean; see below)
cd example
yarn start # Metro
yarn ios # or yarn android
yarn test:ios # XCUITest suite; starts Metro itself if needed
```
--------------------------------
### CocoaPods install with UTF-8 locale
Source: https://github.com/alantoa/poppo/blob/main/AGENTS.md
Install iOS pods. Requires a UTF-8 locale, otherwise CocoaPods fails inside unicode_normalize with Encoding::CompatibilityError.
```sh
cd example/ios && LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 pod install
```
--------------------------------
### Import poppo components
Source: https://github.com/alantoa/poppo/blob/main/README.md
Import the three components and the toast manager hook from the poppo package. Use this as the starting point for any Expo or React Native app that needs tooltips, popovers, or toasts.
```tsx
import { Tooltip, Popover, Toast, useToastManager } from "poppo";
```
--------------------------------
### Set up Toast provider and viewport
Source: https://github.com/alantoa/poppo/blob/main/README.md
Sets up a toast system: wrap the app with Toast.Provider, render toasts in a viewport, and call add from anywhere below the provider. Toast.Root handles animations, swipe-to-dismiss, and countdown pausing.
```tsx
import { Toast, useToastManager } from "poppo";
import { useSafeAreaInsets } from "react-native-safe-area-context";
function Toasts() {
const { toasts } = useToastManager();
return (
{toasts.map((toast) => (
Dismiss
))}
);
}
export default function App() {
return (
);
}
// anywhere below the provider
const toast = useToastManager();
toast.add({ title: "Saved", description: "Your booking was updated" });
```
--------------------------------
### Root
Source: https://github.com/alantoa/poppo/blob/main/README.md
Root component for Tooltip and Popover. Manages open state and callbacks.
```APIDOC
## Root
### Description
Root component for Tooltip and Popover. Manages open state and callbacks.
### Props
| Prop | Type | Notes |
| --- | --- | --- |
| `open` | `boolean` | Controlled open state. |
| `defaultOpen` | `boolean` | Uncontrolled initial state. |
| `onOpenChange` | `(open: boolean) => void` | |
| `onDismiss` | `() => void` | Fires when the popup closes. |
| `disableDismissWhenTouchOutside` | `boolean` | **native** — keep it open on an outside press. |
| `modal` | `boolean` | **web**, popover only — trap focus. |
```
--------------------------------
### createToastManager(options)
Source: https://github.com/alantoa/poppo/blob/main/README.md
Factory function that returns the complete toast manager object.
```APIDOC
## createToastManager(options)
### Description
Creates the full toast manager object for use outside React or in tests.
### Parameters
- **options** (object) - Optional - Configuration options (same as Toast.Provider props).
### Returns
- **add** (function) - Adds a toast.
- **close** (function) - Closes a toast.
- **update** (function) - Updates a toast.
- **finalize(id)** (function) - Removes a toast immediately.
- **pause(id)** (function) - Pauses a toast's countdown.
- **resume(id)** (function) - Resumes a toast's countdown.
- **pauseAll()** (function) - Pauses all toasts.
- **resumeAll()** (function) - Resumes all toasts.
- **getToasts()** (function) - Returns the current toasts.
- **subscribe(fn)** (function) - Subscribes to toast changes.
```
--------------------------------
### Update import from universal-tooltip to poppo
Source: https://github.com/alantoa/poppo/blob/main/alias/universal-tooltip/README.md
Shows the diff to update the import statement from the old package name to the new one. The old import is removed and replaced with the new package name.
```diff
- import { Tooltip } from "universal-tooltip";
+ import { Tooltip } from "poppo";
```
--------------------------------
### Wrap app with GestureHandlerRootView
Source: https://github.com/alantoa/poppo/blob/main/README.md
Wraps the app root with GestureHandlerRootView, required for poppo to work.
```tsx
import { GestureHandlerRootView } from "react-native-gesture-handler";
;
```
--------------------------------
### Toast.Provider
Source: https://github.com/alantoa/poppo/blob/main/README.md
The Toast.Provider component creates the toast manager and accepts configuration props.
```APIDOC
## Toast.Provider
### Description
Creates the toast manager, or accepts an external one via the `toastManager` prop. It controls auto-dismiss, limits, and overflow behavior for toasts.
### Props
- **timeout** (number) - Optional - Auto-dismiss timeout in milliseconds. Default `5000`. `0` keeps toasts until closed.
- **limit** (number) - Optional - Maximum number of toasts the manager keeps live. Default `Infinity`.
- **overflow** ("queue" | "replace") - Optional - Behavior when `limit` is reached. Default `"queue"`.
- **demotedTimeout** (number) - Optional - Ceiling on remaining time for a toast pushed back in the stack. Default `2000`.
- **toastManager** (ToastManager) - Optional - An external manager; when provided, the other props are ignored.
### Usage
Wrap your app with `Toast.Provider` to enable toast functionality.
```
--------------------------------
### Create a Popover with poppo
Source: https://github.com/alantoa/poppo/blob/main/README.md
Renders a popover with the same parts as the tooltip but with a button inside. Uses presetAnimation="fadeIn" for the popup.
```tsx
import { Popover } from "poppo";
import { Pressable, Text, View } from "react-native";
Remove
Remove download?
Remove
;
```
--------------------------------
### Toast anatomy: provider, viewport, root, and per-toast parts
Source: https://github.com/alantoa/poppo/blob/main/README.md
Shows the Toast provider and its composable parts per toast. The provider manages timeout, limit, and overflow; the viewport controls stacking position and presentation; each root handles animation, swipe, and pause-on-touch.
```text
the manager: timeout, limit, overflow
where toasts stack; position, insets, presentation
one toast: animation, swipe, pause-on-touch
·
```
--------------------------------
### Create a Tooltip with poppo
Source: https://github.com/alantoa/poppo/blob/main/README.md
Renders a tooltip with a trigger, portal, positioner, popup, and arrow. The popup is styled with a dark background and rounded corners.
```tsx
import { Tooltip } from "poppo";
import { Text } from "react-native";
Hover me
Saved to your library
;
```
--------------------------------
### Control Popover open state
Source: https://github.com/alantoa/poppo/blob/main/README.md
Shows how to control the popover's open state manually by passing `open` and `onOpenChange`.
```tsx
const [open, setOpen] = useState(false);
{/* ... */}
;
```
--------------------------------
### Popup
Source: https://github.com/alantoa/poppo/blob/main/README.md
Popup component that renders the content of the tooltip or popover. Accepts every `View` prop.
```APIDOC
## Popup
### Description
Popup component that renders the content of the tooltip or popover. Accepts every `View` prop.
### Props
| Prop | Type | Notes |
| --- | --- | --- |
| `style` | `ViewStyle & TextStyle` | See [Styling](#styling). |
| `presetAnimation` | `"none" \| "fadeIn" \| "zoomIn"` | |
| `showDuration` | `number` | **iOS** — ms. |
| `dismissDuration` | `number` | **iOS** — ms. |
| `disableTapToDismiss` | `boolean` | **native** — keep a tooltip open when its bubble is pressed. |
| `onTap` | `() => void` | **native** — fires when a tooltip's bubble is pressed. |
| `className` | `string` | **web** |
```
--------------------------------
### Portal
Source: https://github.com/alantoa/poppo/blob/main/README.md
Portal component for rendering the popup in a different container.
```APIDOC
## Portal
### Description
Portal component for rendering the popup in a different container.
### Props
| Prop | Type | Notes |
| --- | --- | --- |
| `container` | `HTMLElement \| null` | **web** — where to portal into. |
```
--------------------------------
### Tooltip and Popover anatomy: six parts from Root to Arrow
Source: https://github.com/alantoa/poppo/blob/main/README.md
Shows the six parts shared by Tooltip and Popover, from Root to Arrow. The parts are read from the elements written inside Root, so they cannot be wrapped in a custom component. Fragments and conditionals are allowed; in development, Root warns if it cannot find a Popup.
```text
open state
what you press or hover
renders outside the parent
side and offset
the bubble
```
--------------------------------
### Style Tooltip.Popup with View and Text properties
Source: https://github.com/alantoa/poppo/blob/main/README.md
Style a Tooltip.Popup like a React Native View, with text styling when children are plain text. On native, string children use the native bubble and read only backgroundColor, borderRadius, padding*, width/maxWidth, fontSize, color, fontWeight, and fontFamily; other children render via React Native and need their own background and radius. On web, all ViewStyle/TextStyle properties work.
```tsx
Drag to reschedule
```
--------------------------------
### useToastManager()
Source: https://github.com/alantoa/poppo/blob/main/README.md
Hook that provides toast state and actions for React components.
```APIDOC
## useToastManager()
### Description
Returns the visible toasts and methods to add, close, and update toasts from within a React component.
### Returns
- **toasts** (ToastObject[]) - Visible toasts, newest first. Queued toasts are not included until promoted.
- **add(options)** (function) - Shows a toast and returns its `id`. Calling with the same `id` updates the toast and restarts its timer.
- **close(id)** (function) - Starts the exit animation; the manager removes the toast when the animation completes.
- **update(id, options)** (function) - Changes a toast's content without affecting its timer.
### Options (ToastAddOptions)
- **id** (string) - Optional - Unique identifier for the toast.
- **title** (string) - Optional - Toast title.
- **description** (string) - Optional - Toast description.
- **type** ("default" | "success" | "error" | "warning" | "info") - Optional - Toast type.
- **timeout** (number) - Optional - Auto-dismiss timeout in milliseconds.
- **data** (any) - Optional - Custom data for the toast component.
```
--------------------------------
### Configure Toast.Viewport insets with useSafeAreaInsets or custom values
Source: https://github.com/alantoa/poppo/blob/main/README.md
Two ways to pass insets to Toast.Viewport. The first uses the hook useSafeAreaInsets() to respect safe areas; the second passes a custom object, e.g., for a tab bar. Without insets, a bottom toast can sit under the home indicator on modern iPhones. The style prop overrides everything.
```tsx
```
```tsx
```
--------------------------------
### Toast.Viewport with presentation="window" to show toasts above a Modal
Source: https://github.com/alantoa/poppo/blob/main/README.md
Use this viewport to display toasts above a React Native Modal on iOS. The presentation="window" prop moves the viewport into an overlay on the window, which a modal does not cover. On Android and web, it falls back to "inline" with a development warning.
```tsx
```
--------------------------------
### Arrow
Source: https://github.com/alantoa/poppo/blob/main/README.md
Arrow component that renders an arrow pointing to the trigger.
```APIDOC
## Arrow
### Description
Arrow component that renders an arrow pointing to the trigger.
### Props
| Prop | Type | Notes |
| --- | --- | --- |
| `width` | `number` | |
| `height` | `number` | |
| `backgroundColor` | `string` | Defaults to the popup's `style.backgroundColor`. A natively drawn text bubble is one shape, so there it is the popup's colour that wins. |
| `className` | `string` | **web** |
```
--------------------------------
### Positioner
Source: https://github.com/alantoa/poppo/blob/main/README.md
Positioner component that positions the popup relative to the trigger.
```APIDOC
## Positioner
### Description
Positioner component that positions the popup relative to the trigger.
### Props
| Prop | Type | Notes |
| --- | --- | --- |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | Defaults to `"top"`. |
| `sideOffset` | `number` | Distance from the trigger. |
| `align` | `"start" \| "center" \| "end"` | **web** |
```
--------------------------------
### Trigger
Source: https://github.com/alantoa/poppo/blob/main/README.md
Trigger component that toggles the popup on press. Accepts every `Pressable` prop.
```APIDOC
## Trigger
### Description
Trigger component that toggles the popup on press. Accepts every `Pressable` prop.
### Props
| Prop | Type | Notes |
| --- | --- | --- |
| `disabled` | `boolean` | |
| `delay` | `number` | **web**, tooltip only — hover-open delay, ms. |
| `closeDelay` | `number` | **web**, tooltip only — hover-close delay, ms. |
```