Styleframe Logo
Design Tokens

Breakpoints

Create and manage responsive breakpoint design tokens with CSS variables for consistent media query handling and adaptive layouts across your application.

Overview

The breakpoint composable helps you create consistent responsive design systems with minimal code. It generates breakpoint variables that can be easily referenced in media queries throughout your application, enabling flexible theming and consistent responsive behavior across different screen sizes.

Why use breakpoint composables?

Breakpoint composables help you:

  • Centralize breakpoint values: Define all your responsive breakpoints in one place for easy management.
  • Enable flexible theming: Override breakpoint values to instantly adjust responsive behavior across your application.
  • Maintain consistency: Use semantic names to ensure consistent breakpoint usage throughout your design system.
  • Simplify media queries: Reference breakpoint variables instead of hard-coding pixel values in every media query.

useBreakpoint

The useBreakpoint() function creates a set of breakpoint variables from a simple object of breakpoint value definitions.

import { styleframe } from 'styleframe';
import { useBreakpoint } from '@styleframe/theme';

const s = styleframe();

/**
 * Use default breakpoint values
 * {
 *   xs: 0,
 *   sm: 576,
 *   md: 992,
 *   lg: 1200,
 *   xl: 1440,
 * }
 */
const {
    breakpointXs,
    breakpointSm,
    breakpointMd,
    breakpointLg,
    breakpointXl,
} = useBreakpoint(s);

export default s;

Each key in the object becomes a breakpoint variable with the prefix breakpoint--, and the export name is automatically converted to camelCase (e.g., xs → breakpointXs, md → breakpointMd).

Pro tip: Use semantic names like xs, sm, md, lg, and xl to create a consistent responsive system that's easy to understand and maintain across your application.

Creating Custom Breakpoint Variables

You can provide your own custom breakpoint values to match your design system's needs.

import { styleframe } from 'styleframe';
import { useBreakpoint } from '@styleframe/theme';

const s = styleframe();

const {
    breakpointMobile,
    breakpointTablet,
    breakpointLaptop,
    breakpointDesktop,
} = useBreakpoint(s, {
    mobile: 320,
    tablet: 768,
    laptop: 1024,
    desktop: 1440,
} as const);

export default s;

Extending the Default Breakpoint Variables

Styleframe provides default breakpoint values that you can import and use directly, so you don't have to manually define common breakpoint scales:

import { styleframe } from 'styleframe';
import { useBreakpoint, defaultBreakpointValues } from '@styleframe/theme';

const s = styleframe();

/**
 * Use default breakpoint values
 * {
 *   xs: 0,
 *   sm: 576,
 *   md: 992,
 *   lg: 1200,
 *   xl: 1440,
 * }
 */
const {
    breakpointXs,
    breakpointSm,
    breakpointMd,
    breakpointLg,
    breakpointXl,
} = useBreakpoint(s, {
    ...defaultBreakpointValues,
    '2xl': 1920,
});

export default s;

Using these defaults ensures consistency across your project and reduces boilerplate code. You can always override them by passing your own custom values when needed.

Using Breakpoint Variables in Media Queries

Once created, breakpoint variables can be used in media queries throughout your styles:

import { styleframe } from 'styleframe';
import { useBreakpoint } from '@styleframe/theme';

const s = styleframe();
const { ref, selector, media } = s;

const { breakpointSm, breakpointMd, breakpointLg } = useBreakpoint(s, {
    sm: 576,
    md: 992,
    lg: 1200,
} as const);

selector('.container', {
    width: '100%',
    padding: '1rem',
});

// Tablet and up
media(`screen and (min-width: ${breakpointMd.value}px)`, () => {
    selector('.container', {
        maxWidth: '960px',
        margin: '0 auto',
    });
});

// Desktop and up
media(`screen and (min-width: ${breakpointLg.value}px)`, () => {
    selector('.container', {
        maxWidth: '1140px',
    });
});

export default s;
Important: We reference breakpoint values in media queries because CSS does not support referencing variables in media queries yet.

Examples

Range-Based Media Queries

Use breakpoints to create range-based media queries for specific viewport sizes:

import { styleframe } from 'styleframe';
import { useBreakpoint, defaultBreakpointValues } from '@styleframe/theme';

const s = styleframe();
const { ref, selector, media } = s;

const { breakpointSm, breakpointMd, breakpointLg } = 
    useBreakpoint(s, defaultBreakpointValues);

selector('.sidebar', {
    display: 'none',
});

// Show sidebar only on tablets (between sm and lg)
media({ 
    minWidth: ref(breakpointSm), 
    maxWidth: ref(breakpointLg) 
}, () => {
    selector('.sidebar', {
        display: 'block',
        width: '250px',
    });
});

export default s;

Custom Breakpoint Scale

Create a custom breakpoint scale tailored to your specific design needs:

import { styleframe } from 'styleframe';
import { useBreakpoint } from '@styleframe/theme';

const s = styleframe();
const { ref, selector, media } = s;

// Custom breakpoints for a specific application
const {
    breakpointMobile,
    breakpointTablet,
    breakpointDesktop,
    breakpointWide,
    breakpointUltrawide,
} = useBreakpoint(s, {
    mobile: 0,
    tablet: 768,
    desktop: 1024,
    wide: 1920,
    ultrawide: 2560,
} as const);

selector('.hero', {
    minHeight: '400px',
    fontSize: '1.5rem',
});

media(`screen and (min-width: ${breakpointTablet.value}px)`, () => {
    selector('.hero', {
        minHeight: '500px',
        fontSize: '2rem',
    });
});

media(`screen and (min-width: ${breakpointDesktop.value}px)`, () => {
    selector('.hero', {
        minHeight: '600px',
        fontSize: '2.5rem',
    });
});

media(`screen and (min-width: ${breakpointWide.value}px)`, () => {
    selector('.hero', {
        minHeight: '800px',
        fontSize: '3rem',
    });
});

export default s;

Best Practices

  • Use mobile-first approach: Start with mobile styles and progressively enhance for larger screens using min-width media queries.
  • Keep breakpoints consistent: Limit your breakpoints to 4-6 key sizes. Too many breakpoints make maintenance difficult.
  • Choose meaningful values: Use semantic values that reflect device categories or layout changes rather than arbitrary sizes.
  • Avoid device-specific breakpoints: Design for content, not specific devices. Breakpoints should be based on when your layout needs to adapt.
  • Test between breakpoints: Ensure your design works at all viewport sizes, not just at the exact breakpoint values.
  • Consider orientation: For mobile devices, you may want separate breakpoints for portrait and landscape orientations.
  • Document your breakpoint strategy: Make it clear when and why each breakpoint should be used in your design system.
Good to know: We use as const to ensure the object is treated as a constant type. This helps TypeScript infer the return type of the composables and provides better type safety and autocomplete support.

FAQ

Box Shadows

Create and manage box shadow design tokens with CSS variables for consistent elevation and depth effects across your application.

Colors

Create and manage color design tokens with automatic, easily configurable variants, tints, and shades using the oklch color space.