Utilities

Instance methods shared by ReactiveResponsiveState and ContainerState (alongside Subscription API), plus a few standalone functions.

syncCSSVars(options?)

() => void

Syncs all breakpoint keys to CSS custom properties (1 / 0) on document.documentElement (or a custom element). Automatically removes properties for keys removed during a config change.

const stop = state.syncCSSVars({ element: document.body, prefix: '--bp-' })
// → --bp-mobile: 1; --bp-desktop: 0; …
stop() // cleanup

element

HTMLElement · default: document.documentElement

Target HTML element.

prefix

string · default: '--responsive-'

CSS custom property name prefix.

emitDOMEvents(target?, options?)

() => void

Dispatches DOM CustomEvents on target whenever breakpoints change:

• responsive:change — fires on any state change; event.detail is the full state snapshot
• responsive:mobile:enter — fires when mobile becomes true
• responsive:mobile:leave — fires when mobile becomes false

const stop = state.emitDOMEvents(document, { prefix: 'bp:' })

document.addEventListener('bp:change', (e) => console.log(e.detail))
document.addEventListener('bp:mobile:enter', () => initDrawer())
document.addEventListener('bp:desktop:leave', () => destroyDesktopChart())

stop()

prefix (emitDOMEvents)

string · default: 'responsive:'

Custom event name prefix.

toSignal(key, factory)

Signal<boolean>

Binds a breakpoint key to a writable signal from any signals library. The signal is kept in sync via on().

// @preact/signals-core
import { signal } from '@preact/signals-core'
const isMobile = state.toSignal('mobile', signal)
isMobile.value // reactive boolean

// Angular signal
import { signal } from '@angular/core'
const isMobile = state.toSignal('mobile', signal)

// Vue ref
import { ref } from 'vue'
const isMobile = state.toSignal('mobile', ref)

getMediaQueries()

Record<string, string>

Returns the generated CSS media query strings for each breakpoint key.

const mq = state.getMediaQueries()
// { mobile: '(max-width: 600px)', desktop: '(min-width: 961px)' }

getState<T>()

T

Returns a stable snapshot of the current state. Same reference between changes — safe for React's useSyncExternalStore.

getOrder()

string[]

Returns the configured breakpoint order array (or empty array if not set).

hydrate(initialState)

SSR hydration: sets initial state from a server-side snapshot to prevent layout shift. Only updates keys that exist in the current config.

state.hydrate({ mobile: false, tablet: false, desktop: true })

destroy()

Removes all matchMedia / ResizeObserver listeners, clears all subscribers, and cancels any pending debounce timer.

toMediaQueryString(conditions)

string · standalone function (not a state method)

Converts a MediaQueryConfig to a CSS media query string. Useful for CSS-in-JS or debugging.

import { toMediaQueryString } from 'responsive-media'

toMediaQueryString([
  { type: 'min-width', value: 768 },
  { type: 'max-width', value: 1024 },
])
// → "(min-width: 768px) and (max-width: 1024px)"

toMediaQueryString([
  [{ type: 'max-width', value: 600 }],
  [{ type: 'orientation', value: 'portrait' }],
])
// → "(max-width: 600px), (orientation: portrait)"

match(state, map, fallback?)

Standalone function (not a state method). Returns the first value in map whose key is true in state. Priority follows map insertion order.

import { match } from 'responsive-media'
import { responsiveState } from 'responsive-media'

const cols = match(responsiveState.proxy, { mobile: 1, tablet: 2, desktop: 4 })
const View = match(responsiveState.proxy, { mobile: MobileMenu, desktop: DesktopNav })
const label = match(responsiveState.proxy, { sm: 'Compact', lg: 'Full' }, 'Default')

subscribeMediaQuery(query, callback)

() => void · standalone function (not a state method)

Low-level reactive wrapper around a single raw CSS media query string. Framework-agnostic — the Vue and React adapters use this internally.

import { subscribeMediaQuery } from 'responsive-media'

const off = subscribeMediaQuery('(prefers-color-scheme: dark)', (matches) => {
  document.body.classList.toggle('dark', matches)
})
off() // cleanup