Utilities

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

Sync CSS Variables

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.

Emit DOM Events

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.

Convert to Signal

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)

Get Media Queries

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)' }

Get State Snapshot

getState<T>()

T

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

Get Breakpoint Order

getOrder()

string[]

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

SSR Hydration

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 — a key not present in the live config (e.g. after a setConfig() narrowed the active keyset) is dropped. In development builds, dropping a key also logs one console.warn naming every dropped key; production builds stay silent, as before.

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

Destroy

destroy()

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

Media Query String

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

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')

Subscribe to a Media Query

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

Viewport Size

getViewportSize()

{ width: number; height: number }

The window size, 0 by 0 on the server.

subscribeViewportSize(callback, options?)

() => void

Calls callback immediately and then on every resize and orientationchange, throttled. Returns a function that unsubscribes.

import { subscribeViewportSize } from 'responsive-media'

const stop = subscribeViewportSize(({ width, height }) => console.log(width, height), {
  throttle: 200,
})

• throttle — number · default: 100. Milliseconds between callbacks; the first change is delivered at once and the last one is never lost. 0 delivers every event.

State for a Size

statesFromSize(config, size)

Record<string, boolean>

The boolean state a config has for a given { width, height }, with no browser involved. It understands width, height, orientation and aspect-ratio conditions — the same ones as container state. Request hints are built on it.

statesFromSize(config, { width: 390, height: 844 }) // { mobile: true, tablet: true, desktop: false }

SSR Snapshot

getSsrState()

Record<string, boolean>

A stable snapshot of what the state is on the server: the ssrState values, false for the other keys. It is the same in the browser, which is what lets the adapters hydrate without a mismatch.

User Preferences State

getUserPreferencesState()

ReactiveResponsiveState

The shared state over the AccessibilityPreset that useUserPreferences() reads. Use it from plain JavaScript, with the same subscribe, on and getState as any other state.

CSS Export

toMediaQueries, toScssModule, toScssMap, toCustomMedia and toTailwindScreens write a config out for stylesheets — see CSS Integration.