arthur/ui
1
0
Fork 0
mirror of https://github.com/ArthurDanjou/ui.git synced 2026-01-30 03:38:54 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs(use-overlay): add caveats section regarding provide/inject limit (#4287)

Browse Source 
Co-authored-by: Benjamin Canac <canacb1@gmail.com>
This commit is contained in:
Eugen Istoc
2025-06-04 10:01:02 -04:00
committed by GitHub
parent 326bb9a31e
commit d37315cc83
1 changed files with 60 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
docs/content/2.composables/use-overlay.md
View File

@@ -1,6 +1,6 @@
--- ---
title: useOverlay title: useOverlay
description: "A composable to programmatically control overlays." description: 'A composable to programmatically control overlays.'
--- ---
## Usage ## Usage
@@ -9,9 +9,11 @@ Use the auto-imported `useOverlay` composable to programmatically control [Modal
```vue ```vue
<script setup lang="ts"> <script setup lang="ts">
import { LazyModalExample } from '#components'
const overlay = useOverlay() const overlay = useOverlay()
const modal = overlay.create(MyModal) const modal = overlay.create(LazyModalExample)
async function openModal() { async function openModal() {
modal.open() modal.open()
@@ -29,71 +31,73 @@ In order to return a value from the overlay, the `overlay.open().instance.result
### `create(component: T, options: OverlayOptions): OverlayInstance` ### `create(component: T, options: OverlayOptions): OverlayInstance`
Creates an overlay, and returns a factory instance Create an overlay, and return a factory instance.
- Parameters: - Parameters:
- `component`: The overlay component - `component`: The overlay component.
- `options` The overlay options - `options`:
- `defaultOpen?: boolean` Opens the overlay immediately after being created `default: false` - `defaultOpen?: boolean` Open the overlay immediately after being created. Defaults to `false`.
- `props?: ComponentProps`: An optional object of props to pass to the rendered component. - `props?: ComponentProps`: An optional object of props to pass to the rendered component.
- `destroyOnClose?: boolean` Removes the overlay from memory when closed `default: false` - `destroyOnClose?: boolean` Removes the overlay from memory when closed. Defaults to `false`.
### `open(id: symbol, props?: ComponentProps<T>): OpenedOverlay<T>` ### `open(id: symbol, props?: ComponentProps<T>): OpenedOverlay<T>`
Opens the overlay using its `id` Open an overlay by its `id`.
- Parameters: - Parameters:
- `id`: The identifier of the overlay - `id`: The identifier of the overlay.
- `props`: An optional object of props to pass to the rendered component. - `props`: An optional object of props to pass to the rendered component.
### `close(id: symbol, value?: any): void` ### `close(id: symbol, value?: any): void`
Close an overlay using its `id` Close an overlay by its `id`.
- Parameters: - Parameters:
- `id`: The identifier of the overlay - `id`: The identifier of the overlay.
- `value`: A value to resolve the overlay promise with - `value`: A value to resolve the overlay promise with.
### `patch(id: symbol, props: ComponentProps<T>): void` ### `patch(id: symbol, props: ComponentProps<T>): void`
Update an overlay using its `id` Update an overlay by its `id`.
- Parameters: - Parameters:
- `id`: The identifier of the overlay - `id`: The identifier of the overlay.
- `props`: An object of props to update on the rendered component. - `props`: An object of props to update on the rendered component.
### `unmount(id: symbol): void` ### `unmount(id: symbol): void`
Removes the overlay from the DOM using its `id` Remove an overlay from the DOM by its `id`.
- Parameters: - Parameters:
- `id`: The identifier of the overlay - `id`: The identifier of the overlay.
### `isOpen(id: symbol): boolean` ### `isOpen(id: symbol): boolean`
Checks if an overlay its open using its `id` Check if an overlay is open using its `id`.
- Parameters: - Parameters:
- `id`: The identifier of the overlay - `id`: The identifier of the overlay.
### `overlays: Overlay[]` ### `overlays: Overlay[]`
In-memory list of overlays that were created In-memory list of all overlays that were created.
## Overlay Instance API ## Instance API
### `open(props?: ComponentProps<T>): Promise<OpenedOverlay<T>>` ### `open(props?: ComponentProps<T>): Promise<OpenedOverlay<T>>`
Opens the overlay Open the overlay.
- Parameters: - Parameters:
- `props`: An optional object of props to pass to the rendered component. - `props`: An optional object of props to pass to the rendered component.
```vue ```vue
<script setup lang="ts"> <script setup lang="ts">
import { LazyModalExample } from '#components'
const overlay = useOverlay() const overlay = useOverlay()
const modal = overlay.create(MyModalContent) const modal = overlay.create(LazyModalExample)
function openModal() { function openModal() {
modal.open({ modal.open({
@@ -105,23 +109,25 @@ function openModal() {
### `close(value?: any): void` ### `close(value?: any): void`
Close the overlay Close the overlay.
- Parameters: - Parameters:
- `value`: A value to resolve the overlay promise with - `value`: A value to resolve the overlay promise with.
### `patch(props: ComponentProps<T>)` ### `patch(props: ComponentProps<T>)`
Updates the props of the overlay. Update the props of the overlay.
- Parameters: - Parameters:
- `props`: An object of props to update on the rendered component. - `props`: An object of props to update on the rendered component.
```vue ```vue
<script setup lang="ts"> <script setup lang="ts">
import { LazyModalExample } from '#components'
const overlay = useOverlay() const overlay = useOverlay()
const modal = overlay.create(MyModal, { const modal = overlay.create(LazyModalExample, {
title: 'Welcome' title: 'Welcome'
}) })
@@ -141,6 +147,8 @@ Here's a complete example of how to use the `useOverlay` composable:
```vue ```vue
<script setup lang="ts"> <script setup lang="ts">
import { ModalA, ModalB, SlideoverA } from '#components'
const overlay = useOverlay() const overlay = useOverlay()
// Create with default props // Create with default props
@@ -150,7 +158,7 @@ const modalB = overlay.create(ModalB)
const slideoverA = overlay.create(SlideoverA) const slideoverA = overlay.create(SlideoverA)
const openModalA = () => { const openModalA = () => {
// Open Modal A, but override the title prop // Open modalA, but override the title prop
modalA.open({ title: 'Hello' }) modalA.open({ title: 'Hello' })
} }
@@ -160,16 +168,37 @@ const openModalB = async () => {
const input = await modalBInstance.result const input = await modalBInstance.result
// Pass the result from modalB to the slideover, and open it. // Pass the result from modalB to the slideover, and open it
slideoverA.open({ input }) slideoverA.open({ input })
} }
</script> </script>
<template> <template>
<div> <button @click="openModalA">Open Modal</button>
<button @click="openModal">Open Modal</button>
</div>
</template> </template>
``` ```
In this example, we're using the `useOverlay` composable to control multiple modals and slideovers. In this example, we're using the `useOverlay` composable to control multiple modals and slideovers.
## Caveats
### Provide / Inject
When opening overlays programmatically (e.g. modals, slideovers, etc), the overlay component can only access injected values from the component containing `UApp` (typically `app.vue` or layout components). This is because overlays are mounted outside of the page context by the `UApp` component.
As such, using `provide()` in pages or parent components isn't supported directly. To pass provided values to overlays, the recommended approach is to use props instead:
```vue
<script setup lang="ts">
import { LazyModalExample } from '#components'
const providedValue = inject('valueProvidedInPage')
const modal = overlay.create(LazyModalExample, {
props: {
providedValue,
otherData: someValue
}
})
</script>
```