## Overview [#overview] The **Dialog** component is a modal window that displays content on top of the main application, requiring user interaction before continuing. Built on Base UI primitives, it features smooth animations, backdrop blur effects, sticky headers and footers for scrollable content, and flexible sizing options including fullscreen mode. ## Usage [#usage] ```tsx import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogBody, DialogFooter, DialogClose, DialogAction, } from "@tilt-legal/cubitt-components/primitives"; ``` ```tsx }>Open Dialog Dialog Title Dialog description goes here. ``` Using Cubitt's URL-state hooks, you can sync the dialog state with the URL by providing a `paramName`: ```tsx // Opens when ?settings=true in URL }>Open Settings Settings Configure your preferences. // Advanced options: console.log('Dialog open:', value)} > {/* ... */} ``` **Using String Values (e.g., IDs)** Dialog URL state always serializes to strings. There are two modes: **Mode 1: Open for Any Value** (no `paramMatchValue` specified) ```tsx // Opens when ANY value is present: ?dialog=true, ?dialog=abc, etc. // Useful when you just need to track that dialog was opened via URL { console.log("URL value:", value); // Gets the actual string value }} > {/* ... */} ``` **Mode 2: Match Specific Value** (with `paramMatchValue`) This mode is useful when you have multiple dialogs and want each to respond to a specific ID: ```tsx import { Button } from "@tilt-legal/cubitt-components/primitives"; // Button sets item ID // Dialog opens ONLY when ?inspect-dialog=item-001 Inspector: Item 001 This dialog only opens for item-001! ``` This allows multiple dialogs with different `paramMatchValue` props to coexist - each only opens when the URL matches their specific value. ## Examples [#examples] ### Dialog with Form [#dialog-with-form] Dialog containing form inputs for data entry. ```tsx }>Edit Profile Edit Profile Make changes to your profile here. Click save when you're done.
Cancel Save Changes ``` ### Scrollable Content [#scrollable-content] Dialog with long content that scrolls. The header and footer remain sticky with a blurred background effect. ```tsx }>Terms & Conditions Terms and Conditions Please read and accept our terms and conditions.
{/* Long content... */}
 Decline Accept ``` The scrollbar track is automatically inset to clear the sticky header and footer areas. This is controlled via CSS custom properties `--scrollbar-inset-top` and `--scrollbar-inset-bottom`, which default to `3.5rem` inside `DialogContent`. You can override these per-dialog if your header or footer has a non-standard height: ```tsx {/* ... */} ``` ### Fullscreen Dialog [#fullscreen-dialog] Dialog that takes up most of the screen, useful for complex forms or detailed content. ```tsx }>Open Fullscreen Dialog Fullscreen Dialog This dialog takes up most of the screen space.

Content goes here...

 Close ``` ### Without Dismiss Button [#without-dismiss-button] Dialog without the X close button in the top right corner. ```tsx }>Open Without Dismiss Button No Dismiss Button This dialog doesn't have the X close button in the top right. Close ``` ### Nested Dialogs [#nested-dialogs] Open a dialog from within another dialog. The parent dialog will scale down and shift to create a visual hierarchy. ```tsx }>Manage Team Member Manage Team Member View and manage a user in your team.

Name

Sarah Anderson

Email

sarah.anderson@company.com

 {/* Nested Dialog */} }> Edit Details Edit Details Make changes to the member's information.
Cancel Save Changes Close ``` ### URL State [#url-state] Dialog with URL state synchronization for shareable dialog states. ```tsx import { Dialog, DialogAction, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, Button, } from "@tilt-legal/cubitt-components/primitives"; // Button sets URL param directly, Dialog reads it <> Settings This dialog's state is synced with the URL. Check the URL parameter when you open it! Cancel Save ; ``` *** ## API Reference [#api-reference] ### Dialog [#dialog] Root component that manages dialog state. | Prop | Type | Default | Description | | -------------- | ------------------------- | ------- | ------------------------------------------- | | `open` | `boolean` | - | Controlled open state of the dialog. | | `defaultOpen` | `boolean` | `false` | Default open state for uncontrolled usage. | | `onOpenChange` | `(open: boolean) => void` | - | Callback fired when the open state changes. | | `modal` | `boolean` | `true` | Whether the dialog is modal (locks scroll). | | `disabled` | `boolean` | `false` | Whether the dialog is disabled. | #### URL State Props [#url-state-props] When provided with a `paramName`, the dialog will sync its open/closed state with URL parameters via TanStack Router search params. | Prop | Type | Default | Description | | --------------------- | ------------------------- | ------- | ---------------------------------------------------------------------------- | | `paramName` | `string` | — | URL parameter name for syncing state with URL. Enables URL state management. | | `paramMatchValue` | `string` | — | Value that must match for the dialog to open. | | `onUrlValueChange` | `(value: string) => void` | — | Callback when URL parameter value changes. | | `paramClearOnDefault` | `boolean` | `true` | Remove URL param when dialog is closed. | | `paramThrottle` | `number` | — | Throttle URL updates in milliseconds. | | `paramDebounce` | `number` | — | Debounce URL updates in milliseconds. | ### DialogTrigger [#dialogtrigger] Button that opens the dialog. | Prop | Type | Default | Description | | ---------- | -------------------- | ------- | --------------------------------- | | `render` | `React.ReactElement` | - | Custom trigger element to render. | | `disabled` | `boolean` | `false` | Whether the trigger is disabled. | ### DialogContent [#dialogcontent] Container for the dialog content with backdrop and animations. | Prop | Type | Default | Description | | ------------------- | --------- | ------- | ----------------------------------------------------------------------------- | | `showBackdrop` | `boolean` | `true` | Whether to show the backdrop overlay. | | `showDismissButton` | `boolean` | `true` | Whether to show the X close button in the top right. | | `fullscreen` | `boolean` | `false` | Whether the dialog should take up most of the screen. | | `nestedOffset` | `boolean` | `true` | Whether to apply offset transforms for nested dialogs based on nesting depth. | | `className` | `string` | - | Additional CSS classes for the dialog popup. | #### CSS Custom Properties [#css-custom-properties] | Variable | Default | Description | | -------------------------- | --------- | ----------------------------------------------------------- | | `--scrollbar-inset-top` | `3.75rem` | Top margin of the scrollbar track (clears sticky header) | | `--scrollbar-inset-bottom` | `4rem` | Bottom margin of the scrollbar track (clears sticky footer) | ### DialogHeader [#dialogheader] Container for dialog title and description with sticky positioning. | Prop | Type | Default | Description | | ----------- | -------- | ------- | -------------------------------------- | | `className` | `string` | - | Additional CSS classes for the header. | ### DialogTitle [#dialogtitle] The accessible title of the dialog. | Prop | Type | Default | Description | | ----------- | -------- | ------- | ------------------------------------- | | `className` | `string` | - | Additional CSS classes for the title. | ### DialogDescription [#dialogdescription] Description text that provides context about the dialog. | Prop | Type | Default | Description | | ----------- | -------- | ------- | ------------------------------------------- | | `className` | `string` | - | Additional CSS classes for the description. | ### DialogBody [#dialogbody] Container for the main dialog content. | Prop | Type | Default | Description | | ----------- | -------- | ------- | ------------------------------------ | | `className` | `string` | - | Additional CSS classes for the body. | ### DialogFooter [#dialogfooter] Container for dialog actions with sticky positioning. | Prop | Type | Default | Description | | ----------- | -------- | ------- | -------------------------------------- | | `className` | `string` | - | Additional CSS classes for the footer. | ### DialogClose [#dialogclose] Button that closes the dialog (styled as outline button by default). | Prop | Type | Default | Description | | ----------- | -------------------- | ------- | -------------------------------------------- | | `render` | `React.ReactElement` | - | Custom close button element to render. | | `className` | `string` | - | Additional CSS classes for the close button. | ### DialogAction [#dialogaction] Primary action button that closes the dialog (styled as default button). | Prop | Type | Default | Description | | ----------- | -------------------- | ------- | --------------------------------------------- | | `render` | `React.ReactElement` | - | Custom action button element to render. | | `className` | `string` | - | Additional CSS classes for the action button. |