@reach/dialog

  • Version 0.18.0
  • Published
  • 53.3 kB
  • 5 dependencies
  • MIT license

Install

npm i @reach/dialog
yarn add @reach/dialog
pnpm add @reach/dialog

Overview

Accessible React Modal Dialog.

Index

Variables

variable Dialog

const Dialog: Polymorphic.ForwardRefComponent<'div', DialogProps>;
  • Dialog

    High-level component to render a modal dialog window over the top of the page (or another dialog).

    See Also

    • Docs https://reach.tech/dialog#dialog

variable DialogContent

const DialogContent: Polymorphic.ForwardRefComponent<'div', DialogContentProps>;
  • DialogContent

    Low-level component if you need more control over the styles or rendering of the dialog content.

    Note: Must be a child of DialogOverlay.

    Note: You only need to use this when you are also styling DialogOverlay, otherwise you can use the high-level Dialog component and pass the props to it. Any props passed to Dialog component (besides isOpen and onDismiss) will be spread onto DialogContent.

    See Also

    • Docs https://reach.tech/dialog#dialogcontent

variable DialogInner

const DialogInner: Polymorphic.ForwardRefComponent<'div', DialogOverlayProps>;
  • DialogInner

    Low-level component if you need direct access to the portaled dialog wrapper.

    Note: Must be rendered inside of a DialogWrapper.

    See Also

    • Docs https://reach.tech/dialog#dialoginner

variable DialogOverlay

const DialogOverlay: Polymorphic.ForwardRefComponent<'div', DialogOverlayProps>;
  • DialogOverlay

    Low-level component if you need more control over the styles or rendering of the dialog overlay.

    Note: You must render a DialogContent inside.

    See Also

    • Docs https://reach.tech/dialog#dialogoverlay

Functions

function unstable_DialogWrapper

unstable_DialogWrapper: typeof DialogWrapper;
  • DialogWrapper

    Low-level component if you need direct access to the portaled dialog wrapper.

    Note: You must render a DialogInner inside.

Interfaces

interface DialogContentProps

interface DialogContentProps {}
  • See Also

    • Docs https://reach.tech/dialog#dialogcontent-props

property children

children?: React.ReactNode;
  • Accepts any renderable content.

    See Also

    • Docs https://reach.tech/dialog#dialogcontent-children

interface DialogInnerProps

interface DialogOverlayProps extends DialogProps {}

    property dangerouslyBypassFocusLock

    dangerouslyBypassFocusLock?: boolean;
    • By default the dialog locks the focus inside it. Normally this is what you want. This prop is provided so that this feature can be disabled. This, however, is strongly discouraged.

      The reason it is provided is not to disable the focus lock entirely. Rather, there are certain situations where you may need more control on how the focus lock works. This should be complemented by setting up a focus lock yourself that would allow more flexibility for your specific use case.

      If you do set this prop to true, make sure you set up your own FocusLock component. You can likely use react-focus-lock, which is what Reach uses internally by default. It has various settings to allow more customization, but it takes care of a lot of hard work that you probably don't want or need to do.

      See Also

      • Docs https://reach.tech/dialog#dialogoverlay-dangerouslybypassfocuslock

      • https://github.com/theKashey/react-focus-lock

      • https://github.com/reach/reach-ui/issues/615

    property dangerouslyBypassScrollLock

    dangerouslyBypassScrollLock?: boolean;
    • By default the dialog locks scrolling with react-remove-scroll, which also injects some styles on the body element to remove the scrollbar while maintaining its gap to prevent jank when the dialog's open state is toggled. This is almost always what you want in a dialog, but in some cases you may have the need to customize this behavior further.

      This prop will disable react-remove-scroll and allow you to compose your own scroll lock component to meet your needs. Like the dangerouslyBypassFocusLock prop, this is generally discouraged and should only be used if a proper fallback for managing scroll behavior is provided.

      See Also

      • Docs https://reach.tech/dialog#dialogoverlay-dangerouslybypassscrolllock

      • https://github.com/theKashey/react-remove-scroll

    interface DialogOverlayProps

    interface DialogOverlayProps extends DialogProps {}

      property dangerouslyBypassFocusLock

      dangerouslyBypassFocusLock?: boolean;
      • By default the dialog locks the focus inside it. Normally this is what you want. This prop is provided so that this feature can be disabled. This, however, is strongly discouraged.

        The reason it is provided is not to disable the focus lock entirely. Rather, there are certain situations where you may need more control on how the focus lock works. This should be complemented by setting up a focus lock yourself that would allow more flexibility for your specific use case.

        If you do set this prop to true, make sure you set up your own FocusLock component. You can likely use react-focus-lock, which is what Reach uses internally by default. It has various settings to allow more customization, but it takes care of a lot of hard work that you probably don't want or need to do.

        See Also

        • Docs https://reach.tech/dialog#dialogoverlay-dangerouslybypassfocuslock

        • https://github.com/theKashey/react-focus-lock

        • https://github.com/reach/reach-ui/issues/615

      property dangerouslyBypassScrollLock

      dangerouslyBypassScrollLock?: boolean;
      • By default the dialog locks scrolling with react-remove-scroll, which also injects some styles on the body element to remove the scrollbar while maintaining its gap to prevent jank when the dialog's open state is toggled. This is almost always what you want in a dialog, but in some cases you may have the need to customize this behavior further.

        This prop will disable react-remove-scroll and allow you to compose your own scroll lock component to meet your needs. Like the dangerouslyBypassFocusLock prop, this is generally discouraged and should only be used if a proper fallback for managing scroll behavior is provided.

        See Also

        • Docs https://reach.tech/dialog#dialogoverlay-dangerouslybypassscrolllock

        • https://github.com/theKashey/react-remove-scroll

      interface DialogProps

      interface DialogProps {}
      • See Also

        • Docs https://reach.tech/dialog#dialog-props

      property allowPinchZoom

      allowPinchZoom?: boolean;
      • Handle zoom/pinch gestures on iOS devices when scroll locking is enabled. Defaults to false.

        See Also

        • Docs https://reach.tech/dialog#dialog-allowpinchzoom

      property children

      children?: React.ReactNode;
      • Accepts any renderable content.

        See Also

        • Docs https://reach.tech/dialog#dialog-children

      property initialFocusRef

      initialFocusRef?: React.RefObject<any>;
      • By default the first focusable element will receive focus when the dialog opens but you can provide a ref to focus instead.

        See Also

        • Docs https://reach.tech/dialog#dialog-initialfocusref

      property isOpen

      isOpen?: boolean;
      • Controls whether or not the dialog is open.

        See Also

        • Docs https://reach.tech/dialog#dialog-isopen

      property unstable_lockFocusAcrossFrames

      unstable_lockFocusAcrossFrames?: boolean;
      • By default, React Focus Lock prevents focus from being moved outside of the locked element even if the thing trying to take focus is in another frame. Normally this is what you want, as an iframe is typically going to be a part of your page content. But in some situations, like when using Code Sandbox, you can't use any of the controls or the editor in the sandbox while dialog is open because of the focus lock.

        This prop may have some negative side effects and unintended consequences, and it opens questions about how we might distinguish frames that *should* steal focus from those that shouldn't. Perhaps it's best for app devs to decide, and if they use this prop we should advise them to imperatively assign a -1 tabIndex to other iframes that are a part of the page content when the dialog is open.

        https://github.com/reach/reach-ui/issues/536

        Deprecated

      method onDismiss

      onDismiss: (event: React.MouseEvent | React.KeyboardEvent) => void;
      • This function is called whenever the user hits "Escape" or clicks outside the dialog. _It's important to close the dialog onDismiss_.

        The only time you shouldn't close the dialog on dismiss is when the dialog requires a choice and none of them are "cancel". For example, perhaps two records need to be merged and the user needs to pick the surviving record. Neither choice is less destructive than the other, so in these cases you may want to alert the user they need to a make a choice on dismiss instead of closing the dialog.

        See Also

        • Docs https://reach.tech/dialog#dialog-ondismiss

      interface unstable_DialogWrapperProps

      interface DialogWrapperProps extends PortalProps {}

        property isOpen

        isOpen?: boolean;
        • Controls whether or not the dialog is open.

        Namespaces

        namespace unstable_DialogWrapper

        namespace unstable_DialogWrapper {}

          variable displayName

          var displayName: string;

            Package Files (1)

            Dependencies (5)

            Dev Dependencies (6)

            Peer Dependencies (2)

            Badge

            To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

            You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@reach/dialog.

            • Markdown
              [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@reach/dialog)
            • HTML
              <a href="https://www.jsdocs.io/package/@reach/dialog"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>