### 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. | ```