;
}
};
```tsx lines expandable theme={null}
import { Popover, Flex } from "@servicetitan/anvil2";
function App() {
return (
Toggle Popover
The Popover.Content accepts a ReactNode.
);
}
export default App;
```
## Common Examples
```tsx theme={null}
import { Popover } from "@servicetitan/anvil2";
const ExampleComponent = () => {
return (
Click me!This is the popover content.
);
};
```
### Popover basics
To build a popover, three components are required:
* `Popover`: the configurable parent component
* A way to control the open state of the popover. One of:
* `Popover.Button`: an [Anvil2 Button](/docs/web/components/button/code)
* `Popover.Trigger`: used to render a custom trigger component
* `Popover.Content`: the content rendered within the popover
```tsx theme={null}
Trigger ButtonPopover content. Accepts a ReactNode.
```
### Popover placement
Use the `placement` prop on the `Popover` to change the default positioning. The popover will reposition itself if there is not enough space in the default placement.
```tsx theme={null}
...
```
```tsx lines expandable theme={null}
import { Popover, Flex, Grid } from "@servicetitan/anvil2";
function App() {
const btnShared = { style: { width: "100%" }, size: "small" as const };
return (
);
}
export default App;
```
### Controlling popovers
Popovers can be controlled or uncontrolled (default). Control the popover using the `open` prop.
#### Uncontrolled (default)
```tsx lines expandable theme={null}
import { Popover, Flex } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
### Using a custom trigger
To use something other than an [Anvil2 Button](/docs/web/components/button/code) to trigger the popover, use the `Popover.Trigger` component. The `Popover.Trigger` passes a set of props to the `children` that should be passed to an interactive HTML element, such as a `button` or `input`.
```tsx theme={null}
{(props) => }
Content
```
### Popover close button
The `Popover.Close` button can be used to close the popover from within the popover content.
```tsx lines expandable theme={null}
import { Popover, Flex, Text } from "@servicetitan/anvil2";
import Close from "@servicetitan/anvil2/assets/icons/material/round/close.svg";
function App() {
return (
Toggle PopoverPress the close button:
);
}
export default App;
```
On controlled popovers, the `onClick` prop should be used to update the open state:
```tsx theme={null}
setIsOpenState(false)} icon={Close} />
```
### Disabling default closing behavior
By default, an [uncontrolled popover](#controlling-popovers) closes if either the user clicks outside of the popover, or the user presses the "Escape" key. Both of these behaviors can be disabled with props:
#### Disable close on outside click
```tsx lines expandable theme={null}
import { Popover, Flex } from "@servicetitan/anvil2";
function App() {
return (
Toggle Popover
This popover will not close if you click outside.
);
}
export default App;
```
#### Disable close on "Escape" press
```tsx lines expandable theme={null}
import { Popover, Flex } from "@servicetitan/anvil2";
function App() {
return (
Toggle Popover
This popover will not close if you press the "escape" key.
);
}
export default App;
```
### Enabling trapped focus
By default, the popover content does not trap focus so that users can navigate the content with a keyboard without naturally. To enable this behavior, set the `modal` prop of the `Popover` to `true`.
#### Default without trapping
```tsx lines expandable theme={null}
import { Popover, Flex, Text, Button } from "@servicetitan/anvil2";
function App() {
return (
Toggle Popover
Pressing "tab" will trap focus between this button and
the popover trigger button.
Toggle Popover
Pressing "tab" will focus on this button, then go to
the button outside of this popover.
);
}
export default App;
```
### Using with Anvil1
`Popover` from version `1.23.0` uses HTML popover API which utilizes `top-layer`. This feature puts what's inside the `top-layer` to be on the top of entire the HTML. Because of this, there are cases where it does not work well with Anvil1's portaled components.
* While having the `Popover` open, if a portaled Anvil1 component is triggered to open from within, the `Popover` will be on top always. This is something we can potentially adjust in Anvil1 and we have a spike ticket internally for it. If you encounter this issue, please reach out to us.
* While having the `Popover` open, if a `Drawer` or `Dialog` from Anvil1 is triggered to open, not within the `Popover`, the `Popover` will be on top of the `Drawer` or `Dialog`.
## React Accessibility
Most of the accessibility considerations for managing `aria` props and keyboard focus are handled internally. There are some things to keep in mind while working with popovers:
* Always test keyboard navigation for interactive elements within popovers. The user should be able to easily access the elements in a logical order.
* If the popover includes a form, be sure to follow accessible best practices for form building.
* When building a custom trigger using `Popover.Trigger`, be sure to pass the props to an interactive element, as certain `aria` props are included to properly connect the trigger to the content.
For more guidance on creating accessible components, see [building accessible custom components best practices](/docs/accessibility/custom-components).
```tsx theme={null}
{}}
onClickOutside={() => {}}
onOpenAnimationStart={() => {}}
onOpenAnimationComplete={() => {}}
onCloseAnimationStart={() => {}}
onCloseAnimationComplete={() => {}}
>
TriggerContent
```
## `Popover` Props
Should include `Popover.Button` or `Popover.Trigger` and `Popover.Content`.
Controls the default open state on uncontrolled popovers.
Disables all focus management entirely. Useful to delay focus management until
after a transition completes or some other conditional state.
Removes the caret between the trigger and content.
See [Disabling default closing
behavior](/docs/web/components/popover/code#disabling-default-closing-behavior)
See [Disabling default closing
behavior](/docs/web/components/popover/code#disabling-default-closing-behavior)
Traps focus within the popover content.
Removes padding from popover content.
Callback when clicking outside the popover.
Called when the popover is closed, except after mouse exits when `openOnHover`
is `true`.
Callback when closing animation completes.
Callback when closing animation starts.
Callback when opening animation completes.
Callback when opening animation starts.
Use to control open state of the popover.
Opens the popover on hover over the trigger. In most cases, use a
[Tooltip](/docs/web/components/tooltip/code) instead.
```tsx theme={null}
{}}>
Trigger Button
```
## `Popover.Button` Props
The `Popover.Button` component accepts any valid [Anvil2 `Button` component props](/docs/web/components/button/code#prop-table), with one difference — the `children` prop is required in `Popover.Button`.
```tsx theme={null}
Popover content
```
## `Popover.Content` Props
The `Popover.Content` component can accept any valid HTML `div` props.
```tsx theme={null}
{(data) => (
)}
```
## `Popover.Trigger` Props
The `data` parameter includes `"aria-expanded"`, a `ref` for the trigger
component, and some additional accessibility fields.
