Usage

MediaTheme is the provider for content on an inverted surface: an image overlay, a scrim, a toast, or a tooltip. It sets data-astryx-media so text, icons, and buttons use the on-dark or on-light colors. It does not paint a background. Put the surface color on the parent.

mode is required: dark, light, auto, or off. auto measures the color the parent actually paints, translucent layers included, and picks the side whose text color, the theme's --color-on-dark or --color-on-light, reads better on it. It picks off when the surrounding text already clears 3:1. A background image cannot be measured from CSS. The measurement runs again when the surface changes. fallback is the side used before that measurement, and when the surface cannot be measured. The default is dark. off keeps the element and drops the media attribute, so children are not remounted.

useMediaTheme() returns that resolved mode. Import both from @astryx-vue/core/Theme.

<script setup lang="ts">
import { MediaTheme } from '@astryx-vue/core/Theme'
</script>

<template>
  <div style="background: var(--astryx-color-background-inverted, #171717)">
    <MediaTheme mode="auto">
      <p>Readable on this surface</p>
    </MediaTheme>
  </div>
</template>

A theme can add tokens for these surfaces with onDark and onLight on defineTheme().

Best practices

Guidance	Practices
Do	Use it for content over a dark image, a scrim, or another inverted surface.
Do	Prefer mode="auto" when the surface color comes from a theme token.
Do	Set the background on the parent. MediaTheme only flips the token context.
Don't	Use it for page-wide dark mode. Use Theme with mode="dark" or mode="system".

Examples

MediaTheme — Image Overlay

Product launch livestream MediaTheme keeps overlay text and controls readable without hard-coded color overrides.

A common image card pattern: place text and actions over a dark gradient and wrap the overlay content in MediaTheme mode="dark".

MediaTheme — Light Scrim

Bright media surface Use mode="light" when content sits on a light card or scrim.

A light scrim over an image. Use MediaTheme mode="light" so text and ghost buttons use dark-on-light tokens.