);
}
export default App;
```
## Common Examples
```tsx theme={null}
import { Button, Dialog, Flex } from "@servicetitan/anvil2";
import { useState } from "react";
function ExampleComponent() {
const [isOpen, setIsOpen] = useState(true);
return (
);
}
```
### Opening dialogs
Dialogs should be shown and hidden using the `open` prop, rather than conditionally rendering the entire component.
This allows us to follow the HTML standard for `dialog` elements, which is what we render under-the-hood. This also prevents some other issues, such as skipping the exit animation or missing toast messages.
```tsx theme={null}
```
**Do**
```tsx theme={null}
{
shouldBeOpen && ;
}
```
**Don't**
### Rendering content on open
By default, dialog content is rendered on page load, but hidden until the dialog is opened. In some cases, such as making heavy API calls or with content that may require large re-renders based on other user actions, it could be advantageous to wait to render the dialog content.
To render dialog content only when it is opened, conditionally render the `children` based on the state used in the `Dialog.open` prop.
```tsx theme={null}
import { Dialog, Flex, TextField } from "@servicetitan/anvil2";
import { useState } from "react";
function ExampleComponent() {
const [isOpen, setIsOpen] = useState(true);
return (
)
}
```
### Sticky Content
Use the `sticky` prop on `Dialog.Content` to keep important UI elements (like search fields or filters) visible while other content scrolls. This is useful for dialogs with long, scrollable content.
```tsx theme={null}
import { Button, Dialog, Flex, TextField, Text } from "@servicetitan/anvil2";
import { useState } from "react";
function ExampleComponent() {
const [isOpen, setIsOpen] = useState(true);
return (
);
}
```
The search field will remain visible at the top while the list of items scrolls below it.
### Choosing initial focus
By default, the `Dialog` focuses the first focusable element that is not the `Dialog.CancelButton`. To override this behavior, use the `initialFocusResolver` prop to specify which element receives focus when the dialog opens.
The `initialFocusResolver` function receives an array of all focusable elements within the dialog and returns the one that should receive initial focus.
```tsx lines expandable theme={null}
import { Dialog, Flex, Button, TextField } from "@servicetitan/anvil2";
import { useState } from "react";
function App() {
const [isOpen, setIsOpen] = useState(true);
return (
);
}
export default App;
```
### Closing dialogs
Clicking a `Dialog.CancelButton` or the close button inside of `Dialog.Header` will trigger the `Dialog.onClose` to run, where you can add a callback to control the open/close state of the dialog.
```tsx theme={null}
```
#### Closing callbacks
In addition to `onClose`–which indicates a user has chosen to close a dialog–the component also offers two animation callbacks `onCloseAnimationStart` and `onCloseAnimationComplete`.
You may use these callbacks to perform additional actions related to the presentation of the `Dialog`. For example, if you have a dialog containing a form, you may wish to reset the form state after the close animation has played so that the user doesn't see an empty form briefly when closing the dialog.
```tsx theme={null}
const [open, setOpen] = useState(false);
const [field, setField] = useState("");
const handleSubmit = () => {
setOpen(false);
};
const handleDialogAnimationComplete = () => {
setField("");
};
return (
<>
);
```
### Dialogs and Toasts
Due to the way the HTML `dialog` element renders in the browser's top layer, the `Dialog` component includes an internal `Toaster` for rendering toast messages. This should be unnoticeable to implementors and users, but there may be edge cases the result in toasts not rendering as expected.
Please reach out to us in the [#ask-designsystem](https://servicetitan.enterprise.slack.com/archives/CBSRGHTRS) channel on Slack if any edge cases related to dialogs and toasts are found!
## Anti-Patterns
### Conditional rendering
The openness should be controlled by the `open` prop and not by conditional rendering -- this is an anti-pattern for Dialog.
```tsx theme={null}
❌
{condition && }
✅
```
#### Resetting content
HTML Dialog show/hide content but it doesn't remove from the DOM which means the reset doesn't happen automatically. To do the reset, use `key` on `` . Since `` is always present in DOM, you can add conditional to, or in, the `` as well.
#### More details
Dialog uses HTML Dialog which is powered by HTML top-layers. This puts them on top of EVERYTHING regardless z-index and we use the HTML top-layer to avoid stacking context and z-index issues, ensuring Dialog always appear above all content without needing manual z-index adjustments. Dialog internally has custom mechanism to ensure Toasts to be on top for ServiceTitan app and requires Dialog to be present on page load.
```tsx theme={null}
```
## `Dialog` Props
In addition to the props listed below, the `Dialog` component can accept any valid HTML `dialog` props.
When `true`, clicking outside the dialog will not close it.
When `true`, pressing the escape key will not close the dialog.
Enables scroll chaining behavior.
Given an array of focusable elements, returns the element that should receive initial focus.
Callback when clicking outside the dialog.
Indicates the user has closed the dialog. Use this to update your state.
Callback indicating the dialog has animated out. Use this to clean up views as
needed.
Callback indicating the dialog is beginning to animate out.
Callback indicating the dialog has animated in.
Callback indicating the dialog is beginning to animate in.
```tsx theme={null}
Dialog Header
```
## `Dialog.Header` Props
The `Dialog.Header` component can accept any valid HTML header props.
```tsx theme={null}
Dialog content
```
## `Dialog.Content` Props
In addition to the props listed below, the `Dialog.Content` component can accept any valid HTML div props.
When `true`, the content will stick below the header during scroll.
```tsx theme={null}
```
## `Dialog.Footer` Props
```tsx theme={null}
{}}>
Cancel
```
## `Dialog.CancelButton` Props
The `Dialog.CancelButton` component can accept the same props as the `Button` component.
