Props

Name	Type	Default	Description
showOn	OverlayShowOn	'always'	What reveals the overlay while isOpen stays unbound, driven entirely by CSS. always keeps it visible, hover reveals it on hover or when focus enters the container, focus only on focus, and hover-or-focus is an alias of hover. On a touch device hover becomes tap-to-toggle.
isOpen	boolean	-	Visibility controlled from JavaScript, taking precedence over showOn and over the tap toggle. Bind it with v-model:isOpen; leaving it unbound hands visibility back to showOn. While it is false the scrim is hidden and made inert, so its buttons leave the tab order.
scrim	OverlayScrimMode	'dark'	The scrim background, which also decides the surface theme the content inside it uses. dark and light resolve the content against a dark and a light surface respectively; false draws no background and leaves the content on the ambient theme.
position	OverlayPosition	'fill'	How much of the base surface the scrim covers. fill covers all of it, while bottom and top are strips pinned to one edge that slide in from and out to that edge.
align	OverlayAlign	'end'	Alignment of the content inside the scrim. The scrim lays content out in a column, so this is the horizontal axis: start at the leading edge, end at the trailing edge, and center on both axes.

Slots

Name	Description
default	The base content: media, video, artwork, or any bounded block. The scrim covers it.
content	The content drawn inside the scrim. Keep it short — one action or one label. Without this slot the component renders only the base content and draws no scrim.

OverlayScrim

OverlayScrim is the rendering component of the scrim itself, exported from @astryx-vue/core/Overlay for the consumers of useOverlay. Overlay renders it internally, and the props mean the same as above.

Name	Type	Default	Description
scrim	OverlayScrimMode	'dark'	The scrim background and the surface theme its content uses.
position	OverlayPosition	'fill'	How much of the base surface the scrim covers.
align	OverlayAlign	'end'	Alignment of the content inside the scrim.
showOn	OverlayShowOn	'always'	What reveals the overlay while isOpen stays unbound.
isOpen	boolean	-	Controlled visibility. When set, showOn is ignored and a false value marks the scrim inert.

Its default slot is the overlay content. The root carries data-position, data-align, data-scrim, and data-visibility for theming, and the content is wrapped in a data-astryx-media="dark | light" element that switches the surface theme without affecting layout.

useOverlay

useOverlay adds the same overlay behavior to a container that already exists. Its options match the props of Overlay, except that it accepts a ref or a computed for any of them.

Name	Type	Description
containerRef	Ref<HTMLElement | null>	Attach it to the container element with ref="containerRef".
containerProps	ComputedRef<OverlayContainerProps>	The attributes the container needs (scope class, tap toggle), spread with v-bind. They bring the positioning, the clipping, and the tap toggle on a touch device.
scrimProps	ComputedRef<OverlayScrimProps>	Pass them to the OverlayScrim rendered inside the container.
isOpen	ComputedRef<boolean | undefined>	The visibility the scrim actually uses: the bound isOpen, the tap toggle state, or undefined when CSS decides.
hasTouchToggle	ComputedRef<boolean>	Whether the container currently toggles by tap (a touch device in hover mode).
toggle	() => void	Flips the tap toggle state. Ignored while isOpen is bound.

Native attributes

The root element is a <div>.

The following go to the root element:

• HTML attributes.
• aria-* attributes.
• data-* attributes.
• class.
• style.

class is merged with astryx-overlay, and style with the border radius the component writes. A click handler you pass runs alongside the tap toggle.