|
| 1 | +--- |
| 2 | +id: dialog-management |
| 3 | +title: Dialog Management |
| 4 | +--- |
| 5 | + |
| 6 | +This article presents the API the integrators can use to toggle display dialogs in their UIs. The default components that are displayed as dialogs are: |
| 7 | + |
| 8 | +- `ReactionSelector` - allows users to post reactions / emojis to a message |
| 9 | +- `MessageActionsBox` - allows user to select from a list of permitted message actions |
| 10 | + |
| 11 | +The dialog management following this guide is enabled within `MessageList` and `VirtualizedMessageList`. |
| 12 | + |
| 13 | +## Setup dialog display |
| 14 | + |
| 15 | +There are two actors in the play. The first one is the component that requests the dialog to be closed or open and the other is the component that renders the dialog. We will start with demonstrating how to properly render a component in a dialog. |
| 16 | + |
| 17 | +### Rendering a dialog |
| 18 | + |
| 19 | +Component we want to be rendered as a floating dialog should be wrapped inside `DialogAnchor`: |
| 20 | + |
| 21 | +```tsx |
| 22 | +import React, { ElementRef, useRef } from 'react'; |
| 23 | +import { DialogAnchor } from 'stream-chat-react'; |
| 24 | + |
| 25 | +import { ComponentToDisplayOnDialog } from './ComponentToDisplayOnDialog'; |
| 26 | +import { generateUniqueId } from './generateUniqueId'; |
| 27 | + |
| 28 | +const Container = () => { |
| 29 | + // DialogAnchor needs a reference to the element that will toggle the open state. Based on this reference the dialog positioning is calculated |
| 30 | + const buttonRef = useRef<ElementRef<'button'>>(null); |
| 31 | + // providing the dialog is necessary for the dialog to be retrieved from anywhere in the DialogManagerProviderContext |
| 32 | + const dialogId = generateUniqueId(); |
| 33 | + |
| 34 | + return ( |
| 35 | + <> |
| 36 | + <DialogAnchor id={dialogId} placement='top' referenceElement={buttonRef.current} trapFocus> |
| 37 | + <ComponentToDisplayOnDialog /> |
| 38 | + </DialogAnchor> |
| 39 | + </> |
| 40 | + ); |
| 41 | +}; |
| 42 | +``` |
| 43 | + |
| 44 | +### Controlling a dialog's display |
| 45 | + |
| 46 | +The dialog display is controlled via Dialog API. You can access the API via `useDialog()` hook. |
| 47 | + |
| 48 | +```tsx |
| 49 | +import React, { ElementRef, useRef } from 'react'; |
| 50 | +import { DialogAnchor, useDialog, useDialogIsOpen } from 'stream-chat-react'; |
| 51 | + |
| 52 | +import { ComponentToDisplayOnDialog } from './ComponentToDisplayOnDialog'; |
| 53 | +import { generateUniqueId } from './generateUniqueId'; |
| 54 | + |
| 55 | +const Container = () => { |
| 56 | + const buttonRef = useRef<ElementRef<'button'>>(null); |
| 57 | + const dialogId = generateUniqueId(); |
| 58 | + // access the dialog controller which provides the dialog API |
| 59 | + const dialog = useDialog({ id: dialogId }); |
| 60 | + // subscribe to dialog open state changes |
| 61 | + const dialogIsOpen = useDialogIsOpen(dialogId); |
| 62 | + |
| 63 | + return ( |
| 64 | + <> |
| 65 | + <DialogAnchor id={dialogId} placement='top' referenceElement={buttonRef.current} trapFocus> |
| 66 | + <ComponentToDisplayOnDialog /> |
| 67 | + </DialogAnchor> |
| 68 | + <button aria-expanded={dialogIsOpen} onClick={dialog.toggleSingle} ref={buttonRef}> |
| 69 | + Toggle |
| 70 | + </button> |
| 71 | + </> |
| 72 | + ); |
| 73 | +}; |
| 74 | +``` |
| 75 | + |
| 76 | +### Dialog API |
| 77 | + |
| 78 | +Dialog can be controlled via `Dialog` object retrieved using `useDialog()` hook. The hook returns an object with the following API: |
| 79 | + |
| 80 | +- `dialog.open()` - opens the dialog |
| 81 | +- `dialog.close()` - closes the dialog |
| 82 | +- `dialog.toggle()` - toggles the dialog open state. Accepts boolean argument `closeAll`. If enabled closes any other dialog that would be open. |
| 83 | +- `dialog.remove()` - removes the dialog object reference from the state (primarily for cleanup purposes) |
| 84 | + |
| 85 | +Every `Dialog` object carries its own `id` and `isOpen` flag. |
| 86 | + |
| 87 | +### Dialog utility hooks |
| 88 | + |
| 89 | +There are the following utility hooks that can be used to subscribe to state changes or access a given dialog: |
| 90 | + |
| 91 | +- `useDialogIsOpen(id: string)` - allows to observe the open state of a particular `Dialog` instance |
| 92 | +- `useDialog({ id }: GetOrCreateDialogParams)` - retrieves a dialog object that exposes API to manage it |
| 93 | +- `useOpenedDialogCount()` - allows to observe changes in the open dialog count |
| 94 | + |
| 95 | +### Custom dialog management context |
| 96 | + |
| 97 | +Those who would like to render dialogs outside the `MessageList` and `VirtualizedMessageList`, will need to create a dialog management context using `DialogManagerProvider`. |
| 98 | + |
| 99 | +```tsx |
| 100 | +import { DialogManagerProvider } from 'stream-chat-react'; |
| 101 | + |
| 102 | +const Container = () => { |
| 103 | + return <DialogManagerProvider id='custom-dialog-manager-id'></DialogManagerProvider>; |
| 104 | +}; |
| 105 | +``` |
| 106 | + |
| 107 | +Now the children of `DialogAnchor` will be anchored to the parent `DialogManagerProvider`. |
0 commit comments