PiP widgetPro

A floating picture in picture window that stays on top while the conversation continues: drag and throw it to any corner, move it with the arrow keys, minimize it to a bar with a live summary.

Markdown

On this page

ProA cooking timer floating over the conversation. Drag and throw it to a corner, or minimize it.

Installation

$ pnpm dlx shadcn@latest add @chatcn-pro/pip-widget

Usage

tsx

import { PipWidget } from "@/components/ui/chatcn/pro/pip-widget"

<PipWidget
  title="Rigatoni"
  summary={timer.clock}
  safeArea={{ bottom: 88 }}
  onReturn={() => setMode("inline")}
  onClose={() => setOpen(false)}
>
  <Timer />
</PipWidget>

Drag the bar anywhere and let go: the release velocity projects where the window would coast, and it snaps to the nearest corner. Corners are logical, so bottom-end stays at the reading end in RTL. Pass the composer height as safeArea.bottom so the window never covers it.

Minimizing hides the body with hidden instead of unmounting it, so timers, players and widget state keep running. The behavior is also available on its own as usePipWidget with PipWidgetBar, which is how WidgetDisplayModes builds its PiP mode.

Examples

Minimized, corners and RTL

ProThe minimized bar with a live summary and a window parked top start.

Props

Prop	Type	Notes
`title`, `subtitle`, `icon`	`ReactNode`	Bar content
`summary`	`ReactNode`	Shown next to the title while minimized
`corner`, `defaultCorner`, `onCornerChange`	`"top-start" \| "top-end" \| "bottom-start" \| "bottom-end"`	Default `bottom-end`
`minimized`, `defaultMinimized`, `onMinimizedChange`	`boolean`
`onReturn`	`() => void`	Back to the conversation button, and Escape inside the window
`onExpand`	`() => void`	Shows a full screen button
`onClose`	`() => void`	Shows a close button
`actions`	`ReactNode`	Bar buttons, hidden while minimized
`width`, `maxHeight`	`number`	Default 360 and 420
`strategy`, `margin`, `safeArea`		Positioning. Default `fixed`, 16 px
`animateIn`, `minimizable`	`boolean`	Default true

Keyboard

Key	Action
Arrow keys on the grip	Move to the neighbouring corner, announced politely
`Enter`, `Space`	Minimize, restore, full screen, back or close
`Escape`	Back to the conversation, when `onReturn` is set

Accessibility

The window is a named region that does not take focus when it opens: the conversation continues.
The grip is a real button whose description says which corner the window is in and how to move it.
Every bar button has a label and a 44 px target on touch.

Motion

Dragging follows the pointer 1:1 with rubber banding past the edges. Release settles into the corner in 280 ms ease-out on transform only, critically damped.
It enters and minimizes by growing out of its parked corner from 0.96 in 180 ms. Arrow key moves are instant.
Reduced motion: no travel, at most a 150 ms fade.