For AI agents: the complete documentation index is available at /next/llms.txt, the full documentation bundle is available at /next/llms-full.txt, and this page is available as Markdown at /next/ui/components/dialog.md.
lynx-ui logo
lynx-ui
  • English
  • Dialog

    A headless Dialog (modal) component for ReactLynx. It provides backdrop overlay, open/close state management, and enter/exit animations via Presence.
    Info

    You can check the source code to understand how it works, and you're welcome to submit PRs to enhance its capabilities.

    The dialog component. Have a customizable background mask layer.

    Basic Usage

    Structure

    <DialogRoot>
      <DialogTrigger />
      <DialogView>
        <DialogBackdrop />
        <DialogContent>
          <DialogClose />
        </DialogContent>
      </DialogView>
    </DialogRoot>

    Component API

    DialogRoot

    The root component of the Dialog, containing all of its child components.

    debugLogiOSAndroidHarmony
    Typeboolean
    Display debug logs. Open it when you find a bug.
    defaultShowiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Determines whether the dialog should be shown by default. Use this property means the Dialog is uncontrolled.
    forceMountiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Mount the popper and render the content even when it's not shown. At this time, the internal state is "closed".
    onCloseiOSAndroidHarmony
    Type() => void
    Triggered when the popper is actually closed and the potential animation is finished.
    onOpeniOSAndroidHarmony
    Type() => void
    Triggered when the popper is actually show and the potential animation is finished.
    onShowChangeiOSAndroidHarmony
    Type(open: boolean) => void
    Triggered when the dialog is about to be closed, which can be triggered by clicking the backdrop or via a close button. In controlled mode (when show is provided), you should use this handler to update the state that controls the dialog's visibility. In uncontrolled mode, this handler is optional and is called before the dialog's internal state is updated.
    showiOSAndroidHarmony
    Typeboolean
    Whether to show the popper. If this property is not set, the popper will be in controlled mode, meaning the defaultShow property will take no effects. And you have to control behavior of clicking close button and backdrop.
    childreniOSAndroidHarmony
    TypeReactNode | (status: {animating?: boolean, closed?: boolean, entering?: boolean, leaving?: boolean, open?: boolean}) => ReactNode
    children

    State-based styling & rendering

    This component exposes runtime states through one or both of the following channels. The table lists only the channels available for each state:

    • UI variant class — when supported, a class like ui-<state> is toggled on the corresponding component node for selectors such as .ui-<state> { ... }.
    • Render-prop field — when supported and children is a function, the state is passed in via children({ <state>: boolean, ... }) for runtime-driven rendering.

    DialogRoot exposes the following render prop states.

    Render PropTypeDescription
    animatingbooleanThe popper is doing the animations. Takes effect when transition:true.
    closedbooleanThe popper is closed. If it's force mounted, the initial status will be closed.
    enteringbooleanThe popper is performing the entering animation. Takes effect when transition:true.
    leavingbooleanThe popper is performing the leaving animation. Takes effect when transition:true.
    openbooleanThe popper is opened.

    DialogTrigger

    The trigger of the dialog. Controls the display of the popper.

    classNameiOSAndroidHarmony
    Typestring
    className
    disablediOSAndroidHarmony
    Typeboolean·Defaultfalse
    Determines whether the trigger component is disabled. When true, the component will be in a disabled state and cannot be interacted with.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    transitioniOSAndroidHarmony
    Typeboolean
    When true, className includes transition classes such as 'ui-entering', 'ui-leaving', and 'ui-animating'.
    childreniOSAndroidHarmony
    TypeReactNode | (status: {active: boolean, busy: boolean}) => ReactNode
    The content of the trigger component. It can be a function that returns a ReactNode or a ReactNode itself.

    UI variants applied by DialogTrigger based on its render state.

    Class NameRender PropTypeDescription
    ui-activeactivebooleanRender function state: active. Applied while the composed dialog button is pressed and not disabled.
    ui-animating—booleanApplied when `status.animating` is true.
    ui-busybusybooleanRender function state: busy. Applied while the dialog is entering or leaving.
    ui-closed—booleanApplied when `status.closed` is true.
    ui-disabled—booleanApplied when the dialog button is explicitly disabled or the dialog is busy.
    ui-entering—booleanApplied when `status.entering` is true.
    ui-leaving—booleanApplied when `status.leaving` is true.
    ui-open—booleanApplied when `status.open` is true.

    DialogBackdrop

    The backdrop mask of the dialog.

    childreniOSAndroidHarmony
    TypeReactNode
    children
    classNameiOSAndroidHarmony
    Typestring
    className
    clickToCloseiOSAndroidHarmony
    Typeboolean·Defaulttrue
    Determines whether clicking on the backdrop closes the dialog. This prop acts as a behavior switch for the backdrop's click event. When true, clicking the backdrop will trigger the onClose callback and close the dialog if the dialog is in uncontrolled mode (when show is not provided). When false, clicking the backdrop will have no effect.
    delayed
    Typeboolean
    If the content needs a delayed first screen to do first render, you need to set this property to true.
    dialogBackdropPropsiOSAndroidHarmony
    TypeViewProps
    DialogBackdrop supports original view props to be directly spread in this prop.
    onClickiOSAndroidHarmony
    Type() => void
    Triggered when the backdrop is clicked.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    transitioniOSAndroidHarmony
    Typeboolean
    When true, className includes transition classes such as 'ui-entering', 'ui-leaving', and 'ui-animating'.

    UI variants applied by DialogBackdrop.

    Class NameDescription
    ui-animatingApplied when `status.animating` is true.
    ui-closedApplied when `status.closed` is true.
    ui-enteringApplied when `status.entering` is true.
    ui-leavingApplied when `status.leaving` is true.
    ui-openApplied when `status.open` is true.

    DialogView

    View container. When 'container' is set correctly, the underlying layer will be replaced with overlay; otherwise, it will be a regular view. When the underlying layer is overlay, the 'level' property can be used to control the hierarchical relationship. For a regular view, use 'z-index' to control the hierarchical relationship. If this dialog needs to be used outside of LynxView, consider enabling overlay.

    classNameiOSAndroidHarmony
    Typestring
    className
    containeriOSAndroidHarmony
    Typestring
    If you want to use the poppers outside of the LynxView, you need to set this property. The value is the name of the native container.
    debugLogiOSAndroidHarmony
    Typeboolean
    Display debug logs. Open it when you find a bug.
    dialogViewPropsiOSAndroidHarmony
    TypeViewProps | OverlayProps
    Additional props that will be spread to the underlying OverlayView element
    idiOSAndroidHarmony
    Typestring
    id
    overlayLeveliOSAndroidHarmony
    Type1 | 2 | 3 | 4
    Only works when the 'container' is set to non-empty string. Adjust nearby elements display level.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    transitioniOSAndroidHarmony
    Typeboolean
    When true, className includes transition classes such as 'ui-entering', 'ui-leaving', and 'ui-animating'.
    childreniOSAndroidHarmony
    TypeReactNode | (status: {open?: boolean, closed?: boolean, leaving?: boolean, entering?: boolean, animating?: boolean}) => ReactNode
    children

    UI variants applied by DialogView based on its render state.

    Class NameRender PropTypeDescription
    ui-animatinganimatingbooleanThe popper is doing the animations. Takes effect when transition:true. Applied when `status.animating` is true.
    ui-closedclosedbooleanThe popper is closed. If it's force mounted, the initial status will be closed. Applied when `status.closed` is true.
    ui-enteringenteringbooleanThe popper is performing the entering animation. Takes effect when transition:true. Applied when `status.entering` is true.
    ui-leavingleavingbooleanThe popper is performing the leaving animation. Takes effect when transition:true. Applied when `status.leaving` is true.
    ui-openopenbooleanThe popper is opened. Applied when `status.open` is true.

    DialogContent

    The main content of the dialog.

    childreniOSAndroidHarmony
    TypeReactNode
    children
    classNameiOSAndroidHarmony
    Typestring
    className
    delayed
    Typeboolean
    If the content needs a delayed first screen to do first render, you need to set this property to true.
    dialogContentPropsiOSAndroidHarmony
    TypeViewProps
    DialogContent supports original view props to be directly spread in this prop.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    transitioniOSAndroidHarmony
    Typeboolean
    When true, className includes transition classes such as 'ui-entering', 'ui-leaving', and 'ui-animating'.

    UI variants applied by DialogContent.

    Class NameDescription
    ui-animatingApplied when `status.animating` is true.
    ui-closedApplied when `status.closed` is true.
    ui-enteringApplied when `status.entering` is true.
    ui-leavingApplied when `status.leaving` is true.
    ui-openApplied when `status.open` is true.

    DialogClose

    The close component of the Dialog, used to close the dialog.

    classNameiOSAndroidHarmony
    Typestring
    className
    disablediOSAndroidHarmony
    Typeboolean·Defaultfalse
    Determines whether the close component is disabled. When true, the component will be in a disabled state and cannot be interacted with.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    transitioniOSAndroidHarmony
    Typeboolean
    When true, className includes transition classes such as 'ui-entering', 'ui-leaving', and 'ui-animating'.
    childreniOSAndroidHarmony
    TypeReactNode | (status: {active: boolean, busy: boolean}) => ReactNode
    The content of the close component. It can be a function that returns a ReactNode or a ReactNode itself.

    UI variants applied by DialogClose based on its render state.

    Class NameRender PropTypeDescription
    ui-activeactivebooleanRender function state: active. Applied while the composed dialog button is pressed and not disabled.
    ui-animating—booleanApplied when `status.animating` is true.
    ui-busybusybooleanRender function state: busy. Applied while the dialog is entering or leaving.
    ui-closed—booleanApplied when `status.closed` is true.
    ui-disabled—booleanApplied when the dialog button is explicitly disabled or the dialog is busy.
    ui-entering—booleanApplied when `status.entering` is true.
    ui-leaving—booleanApplied when `status.leaving` is true.
    ui-open—booleanApplied when `status.open` is true.
    Except as otherwise noted, this work is licensed under a Creative Commons Attribution 4.0 International License, and code samples are licensed under the Apache License 2.0.