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–21
npm install ngx-mq@2

Breakpoint API

Configuration

Create a custom breakpoint map or use one of the built-in presets (e.g. provideTailwindBreakpoints()).

import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app/app.component';
import { provideBreakpoints } 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,
    }),
  ],
});

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

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. | | anyHover | options?: CreateMediaQueryOptions | Signal<boolean> | true when any available input device supports hover capability. | | pointer | value: 'fine' \| 'coarse' \| 'none', options?: CreateMediaQueryOptions | Signal<boolean> | true when the user's primary input device matches the specified pointer type. | | anyPointer | value: 'fine' \| 'coarse' \| 'none', options?: CreateMediaQueryOptions | Signal<boolean> | true when any available input device matches the specified pointer type. | | colorGamut | value: 'srgb' \| 'p3' \| 'rec2020', options?: CreateMediaQueryOptions | Signal<boolean> | true when the user's display supports the specified color gamut. |

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 Material 2 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';

Sponsors

Contributing

CONTRIBUTING.md