or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

index.mddocs/

Chakra UI Breakpoint Utils

Chakra UI Breakpoint Utils is a TypeScript utility library that provides a comprehensive set of functions for managing CSS breakpoints and responsive design patterns. It offers functionality for converting between different breakpoint notation formats (object to array and vice versa), analyzing breakpoint configurations, generating CSS media queries, and mapping responsive properties across different screen sizes.

Package Information

  • Package Name: @chakra-ui/breakpoint-utils
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @chakra-ui/breakpoint-utils

Core Imports

import {
  breakpoints,
  mapResponsive,
  objectToArrayNotation,
  arrayToObjectNotation,
  isResponsiveObjectLike,
  isCustomBreakpoint,
  px,
  toMediaQueryString,
  analyzeBreakpoints,
  type AnalyzeBreakpointsReturn
} from "@chakra-ui/breakpoint-utils";

For CommonJS:

const {
  breakpoints,
  mapResponsive,
  objectToArrayNotation,
  arrayToObjectNotation,
  isResponsiveObjectLike,
  isCustomBreakpoint,
  px,
  toMediaQueryString,
  analyzeBreakpoints
} = require("@chakra-ui/breakpoint-utils");

Basic Usage

import { 
  breakpoints, 
  objectToArrayNotation, 
  arrayToObjectNotation,
  analyzeBreakpoints 
} from "@chakra-ui/breakpoint-utils";

// Convert object notation to array notation
const responsive = { base: "16px", md: "24px", lg: "32px" };
const arrayValues = objectToArrayNotation(responsive);
// Result: ["16px", null, "24px", "32px"]

// Convert array notation back to object notation  
const objectValues = arrayToObjectNotation(arrayValues);
// Result: { base: "16px", md: "24px", lg: "32px" }

// Analyze breakpoint configuration
const config = { base: "0px", sm: "480px", md: "768px", lg: "992px" };
const analysis = analyzeBreakpoints(config);

console.log(analysis?.media);
// Result: [null, "@media screen and (min-width: 480px)", ...]

Architecture

The library is organized around two main functional areas:

  • Responsive Utilities: Functions for handling responsive value notation conversion and mapping
  • Breakpoint Analysis: Advanced breakpoint configuration analysis with media query generation

The library supports two responsive notation patterns:

  1. Array notation: [value1, value2, value3] - values by breakpoint index
  2. Object notation: {base: value1, md: value2, lg: value3} - values by breakpoint name

Capabilities

Breakpoint Constants

Predefined breakpoint names used throughout the Chakra UI ecosystem.

const breakpoints: readonly string[];

The breakpoints array contains: ["base", "sm", "md", "lg", "xl", "2xl"]

Responsive Value Mapping

Maps responsive values through a transformation function, handling arrays, objects, and single values.

/**
 * Maps a responsive prop through a mapper function
 * @param prop - The responsive value (array, object, or single value)
 * @param mapper - Function to transform each value
 * @returns Mapped responsive value in same format as input
 */
function mapResponsive(prop: any, mapper: (val: any) => any): any;

Usage Example:

import { mapResponsive } from "@chakra-ui/breakpoint-utils";

// Map object notation
const sizes = { base: 16, md: 24, lg: 32 };
const pixels = mapResponsive(sizes, (val) => `${val}px`);
// Result: { base: "16px", md: "24px", lg: "32px" }

// Map array notation  
const arrayValues = [16, null, 24, 32];
const arrayPixels = mapResponsive(arrayValues, (val) => val ? `${val}px` : null);
// Result: ["16px", null, "24px", "32px"]

Notation Conversion

Convert between object and array responsive notation formats.

/**
 * Converts responsive object notation to array notation
 * @param obj - Object with breakpoint keys and values
 * @param bps - Custom breakpoint names (defaults to standard breakpoints)
 * @returns Array of values in breakpoint order, null-padded
 */
function objectToArrayNotation(
  obj: Record<string, any>,
  bps?: string[]
): any[];

/**
 * Converts responsive array notation to object notation
 * @param values - Array of values in breakpoint order
 * @param bps - Custom breakpoint names (defaults to standard breakpoints)  
 * @returns Object with breakpoint keys and non-null values
 */
function arrayToObjectNotation(
  values: any[], 
  bps?: string[]
): Record<string, any>;

Usage Examples:

import { objectToArrayNotation, arrayToObjectNotation } from "@chakra-ui/breakpoint-utils";

// Object to array
const objValues = { base: "small", md: "medium", xl: "large" };
const arrayResult = objectToArrayNotation(objValues);
// Result: ["small", null, "medium", null, "large"]

// Array to object
const arrayValues = ["small", "medium", null, "large"];
const objectResult = arrayToObjectNotation(arrayValues);
// Result: { base: "small", sm: "medium", lg: "large" }

Responsive Pattern Detection

Check if objects contain only responsive breakpoint keys.

/**
 * Checks if an object contains only responsive breakpoint keys
 * @param obj - Object to test
 * @param bps - Custom breakpoint names (defaults to standard breakpoints)
 * @returns True if all keys are valid breakpoint names
 */
function isResponsiveObjectLike(
  obj: Record<string, any>,
  bps?: string[]
): boolean;

/**
 * Returns true if the given value is a custom breakpoint (not numeric index)
 * @param v - String value to test
 * @returns True if value is not a numeric string
 */
function isCustomBreakpoint(v: string): boolean;

Usage Examples:

import { isResponsiveObjectLike, isCustomBreakpoint } from "@chakra-ui/breakpoint-utils";

// Test responsive object
const responsive = { base: "16px", md: "24px" };
const isResponsive = isResponsiveObjectLike(responsive);
// Result: true

const notResponsive = { width: "100px", height: "50px" };
const isNotResponsive = isResponsiveObjectLike(notResponsive);
// Result: false

// Test custom breakpoint
console.log(isCustomBreakpoint("md"));    // true
console.log(isCustomBreakpoint("0"));     // false
console.log(isCustomBreakpoint("base"));  // true

CSS Value Processing

Convert values to pixel units and generate CSS media queries.

/**
 * Converts a value to pixels, adding 'px' unit if unitless
 * @param value - Number, string, or null value
 * @returns String with px unit or original string/null value
 */
function px(value: number | string | null): string | null;

/**
 * Generates CSS media query string from min/max width values
 * @param min - Minimum width value (null for no min-width)
 * @param max - Maximum width value (undefined for no max-width)
 * @returns Complete CSS media query string
 */
function toMediaQueryString(min: string | null, max?: string): string;

Usage Examples:

import { px, toMediaQueryString } from "@chakra-ui/breakpoint-utils";

// Convert to pixels
console.log(px(16));        // "16px"
console.log(px("24"));      // "24px"
console.log(px("2rem"));    // "2rem"
console.log(px(null));      // null

// Generate media queries
const minOnly = toMediaQueryString("768px");
// Result: "@media screen and (min-width: 768px)"

const minMax = toMediaQueryString("768px", "991.98px");
// Result: "@media screen and (min-width: 768px) and (max-width: 991.98px)"

const maxOnly = toMediaQueryString(null, "767.98px");
// Result: "@media screen and (max-width: 767.98px)"

Breakpoint Analysis

Comprehensive analysis of breakpoint configurations with media query generation.

/**
 * Analyzes breakpoint configuration and returns normalized data with media queries
 * @param breakpoints - Object mapping breakpoint names to CSS values
 * @returns Analysis object with normalized data and utility methods, or null
 */
function analyzeBreakpoints(breakpoints: Record<string, any>): AnalyzeBreakpointsReturn | null;

interface AnalyzeBreakpointsReturn {
  /** Set of breakpoint keys */
  keys: Set<string>;
  /** Array of breakpoint values with object properties */
  normalized: string[];
  /** Test if an object uses responsive breakpoint keys */
  isResponsive(test: Record<string, any>): boolean;
  /** Breakpoints as sorted object */
  asObject: Record<string, any>;
  /** Breakpoints as array */
  asArray: string[];
  /** Array of detailed breakpoint query information */
  details: Array<{
    _minW: string;
    breakpoint: string;
    minW: string;
    maxW?: string;
    maxWQuery: string;
    minWQuery: string;
    minMaxQuery: string;
  }>;
  /** Get breakpoint details by key */
  get(key: string): BreakpointQueryDetail | undefined;
  /** Array of media query strings */
  media: Array<string | null>;
  /** Convert object notation to array notation (throws if input is not an object) */
  toArrayValue(test: Record<string, any>): any[];
  /** Convert array notation to object notation (throws if input is not an array) */
  toObjectValue(test: any[]): Record<string, any>;
}

Usage Example:

import { analyzeBreakpoints } from "@chakra-ui/breakpoint-utils";

const config = {
  base: "0px",
  sm: "480px", 
  md: "768px",
  lg: "992px",
  xl: "1200px"
};

const analysis = analyzeBreakpoints(config);

if (analysis) {
  // Access media queries
  console.log(analysis.media);
  // Result: [null, "@media screen and (min-width: 480px)", ...]
  
  // Test responsive objects
  const isResponsive = analysis.isResponsive({ base: "16px", md: "24px" });
  // Result: true
  
  // Convert between notations
  const arrayValues = analysis.toArrayValue({ base: "small", md: "large" });
  // Result: ["small", null, "large", null, null]
  
  const objectValues = analysis.toObjectValue(["small", "medium", "large"]);
  // Result: { base: "small", sm: "medium", md: "large" }
  
  // Get specific breakpoint details
  const mdBreakpoint = analysis.get("md");
  console.log(mdBreakpoint?.minWQuery);
  // Result: "@media screen and (min-width: 768px)"
}

Types

type AnalyzeBreakpointsReturn = ReturnType<typeof analyzeBreakpoints>;

interface BreakpointQueryDetail {
  _minW: string;
  breakpoint: string;
  minW: string;
  maxW?: string;
  maxWQuery: string;
  minWQuery: string;
  minMaxQuery: string;
}