ngx-mq: A TypeScript repository from martsinlabs

Signal-Powered Breakpoints & Media Queries

Features

Lightweight
SSR-safe
Auto-cleanup
Angular 16 — next
Well-tested

Introduction

Built on the native matchMedia API, NGX-MQ brings a signal-based and declarative way to handle breakpoints and media queries in Angular. Lifecycle management is fully automated via DestroyRef, removing the need for manual cleanup. Under the hood, it leverages the Multiton and Flyweight patterns for efficient instance reuse and consistent behavior across your app.

Tip: Always call query utilities within Angular’s injection context to keep them in sync with the framework’s lifecycle.

Live Demo

Try it on StackBlitz

Installation

Choose the package version that matches your Angular setup:

# For Angular 16–18
npm install ngx-mq@1

# For Angular 19–20
npm install ngx-mq@2

Breakpoint API

Configuration

Provide your map at the application bootstrap.

import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app/app.component';
import {
  provideBreakpoints,
  provideTailwindBreakpoints,
  provideBootstrapBreakpoints,
  provideMaterialBreakpoints,
  provideBreakpointEpsilon,
} from 'ngx-mq';

bootstrapApplication(AppComponent, {
  providers: [
    // Define a custom map (keys are named ranges, values are widths in pixels)
    provideBreakpoints({
      sm: 640,
      md: 768,
      lg: 1024,
    }),

    // Or use one of the built-in presets
    // provideTailwindBreakpoints(),
    // provideBootstrapBreakpoints(),
    // provideMaterialBreakpoints(),

    // Configure epsilon if needed (default: 0.02)
    provideBreakpointEpsilon(0.02),
  ],
});

Available presets

Tailwind → sm: 640, md: 768, lg: 1024, xl: 1280, 2xl: 1536
Bootstrap → sm: 576, md: 768, lg: 992, xl: 1200, xxl: 1400
Material → sm: 600, md: 905, lg: 1240, xl: 1440

Note: Epsilon is a small value subtracted from upper bounds to prevent adjacent ranges from overlapping.

BP-related utilities

Function	Parameters	Returns	Description
`up`	`bp: string, options?: CreateMediaQueryOptions`	`Signal<boolean>`	`true` when viewport width ≥ breakpoint
`down`	`bp: string, options?: CreateMediaQueryOptions`	`Signal<boolean>`	`true` when viewport width < breakpoint
`between`	`minBp: string, maxBp: string, options?: CreateMediaQueryOptions`	`Signal<boolean>`	`true` when viewport width is in range [a, b]

Tip: Wrap these APIs into reusable helpers:

// viewport-utils.ts
import { Signal } from '@angular/core';
import { up, down, between } from 'ngx-mq';

export const isMobile = (): Signal<boolean> => down('md');
export const isTablet = (): Signal<boolean> => between('md', 'lg');
export const isDesktop = (): Signal<boolean> => up('lg');

Common utilities

Utils exposing common CSS media features.

Function	Parameters	Returns	Description
`orientation`	`value: 'portrait' \| 'landscape', options?: CreateMediaQueryOptions`	`Signal<boolean>`	`true` when the current screen orientation matches the specified value.
`colorScheme`	`value: 'light' \| 'dark', options?: CreateMediaQueryOptions`	`Signal<boolean>`	`true` when the system color scheme matches the specified value.
`displayMode`	`value: DisplayModeOption, options?: CreateMediaQueryOptions`	`Signal<boolean>`	`true` when the current display mode matches the specified value.
`reducedMotion`	`options?: CreateMediaQueryOptions`	`Signal<boolean>`	`true` when the user has enabled reduced motion.
`hover`	`options?: CreateMediaQueryOptions`	`Signal<boolean>`	`true` when the user's primary input device supports hover capability.

Generic Media Query API

Works with any valid CSS media query and returns a Signal<boolean> which automatically updates when the query result changes.

Function	Parameters	Returns	Description
`matchMediaSignal`	`query: string, options?: CreateMediaQueryOptions`	`Signal<boolean>`	Provides a signal representing the state of a media query

Tip: Use this API for media queries that are not part of your breakpoint map.

import { Signal } from '@angular/core';
import { matchMediaSignal } from 'ngx-mq';

// Example: track orientation changes
export const isLandscape = (): Signal<boolean> => matchMediaSignal('(orientation: landscape)');

Providers

These functions return standard Angular Provider instances that can be injected at any level of the application hierarchy.

Provider	Parameters	Description
`provideBreakpoints()`	`bps: MqBreakpoints`	Registers a custom set of breakpoints.
`provideTailwindBreakpoints()`	none	Registers the default Tailwind CSS breakpoints.
`provideBootstrapBreakpoints()`	none	Registers the default Bootstrap breakpoints.
`provideMaterialBreakpoints()`	none	Registers the default Angular Material breakpoints.
`provideBreakpointEpsilon()`	`epsilon: number`	Sets the epsilon threshold used when comparing breakpoint values.
`provideSsrValue()`	`value: boolean`	Defines the static signal value used during SSR, since media queries are not available on the server. Defaults to `false`.

💡 To register these as environment providers, wrap them with makeEnvironmentProviders().

Types

export type MqBreakpoints = Record<string, number>;

export interface CreateMediaQueryOptions {
  /**
   * Static signal value used during SSR.
   */
  ssrValue?: boolean;

  /**
   * A debug name for the signal. Used in Angular DevTools to identify the signal.
   */
  debugName?: string;
}

export type DisplayModeOption =
  | 'browser'
  | 'fullscreen'
  | 'standalone'
  | 'minimal-ui'
  | 'window-controls-overlay'
  | 'picture-in-picture';

Contributing

CONTRIBUTING.md

martsinlabs/ngx-mq