Overlay API

Low-level overlay management functions for creating, updating, and removing overlays programmatically.

Import

import {
    presentOverlay,
    createOverlayInjection,
    removeOverlayInjection,
    updateOverlayProps,
    dismissOverlayInjectionById,
    dismissOverlayInjectionByInstance
} from '@zyno-io/vue-foundation';

presentOverlay(component, props, options?)

Shows a component as an overlay and returns a Promise that resolves when the overlay is dismissed.

const result = await presentOverlay(MyModal, {
    title: 'Edit User',
    user: currentUser
});

Overlay components must have a callback prop. When the component calls props.callback(result), the overlay is dismissed and the promise resolves with result. You don't pass callback yourself -- presentOverlay injects it automatically.

Options

interface OverlayOptions {
    anchor?: OverlayAnchorOptions; // Position relative to an element
    onCallback?: (result) => void | Promise<boolean>; // Return false to prevent dismissal
}

See the Overlay System guide for full details on anchored overlays.

createOverlayInjection(component, props)

Low-level function to create an overlay without Promise wrapping.

const injection = createOverlayInjection(MyComponent, props);

updateOverlayProps(injection, props)

Update props on an existing overlay injection.

updateOverlayProps(injection, { message: 'Updated!' });

removeOverlayInjection(injection)

Remove an overlay injection from the overlay container.

removeOverlayInjection(injection);

dismissOverlayInjectionById(overlayId)

Dismiss an overlay by its ID.

dismissOverlayInjectionById(overlayId);

dismissOverlayInjectionByInstance(instance)

Dismiss an overlay by its component instance.

dismissOverlayInjectionByInstance(componentInstance);

Demo

<template>
    <div>
        <button @click="openOverlay">Present Overlay</button>
        <p v-if="overlayResult" style="margin-top: 12px; font-size: 14px; color: var(--vp-c-text-2)">
            Overlay result: <strong>{{ overlayResult }}</strong>
        </p>
    </div>
</template>

<script lang="ts" setup>
import { presentOverlay, VfModal } from '@zyno-io/vue-foundation';
import { ref, defineComponent, h } from 'vue';

const overlayResult = ref('');

const SimpleOverlay = defineComponent({
    props: {
        callback: { type: Function, required: true }
    },
    setup(props) {
        return () =>
            h(
                VfModal,
                { closeOnMaskClick: true },
                {
                    header: () => 'Overlay Example',
                    default: () => h('p', 'This component was shown using presentOverlay(). Click a button or the backdrop to close.'),
                    footer: () => [
                        h('button', { type: 'button', onClick: () => props.callback('cancelled') }, 'Cancel'),
                        h('button', { onClick: () => props.callback('confirmed') }, 'Confirm')
                    ]
                }
            );
    }
});

async function openOverlay() {
    const result = await presentOverlay(SimpleOverlay, {});
    overlayResult.value = String(result);
}
</script>