useBreakpoints

Category

Browser

Export Size

1.10 kB

Last Changed

5 days ago

Reactive viewport breakpoints

Demo

Usage

import { breakpointsTailwind, useBreakpoints } from '@reause/core'

const breakpoints = useBreakpoints(breakpointsTailwind)

const smAndLarger = breakpoints.greaterOrEqual('sm') // sm and larger
const largerThanSm = breakpoints.greater('sm') // only larger than sm
const lgAndSmaller = breakpoints.smallerOrEqual('lg') // lg and smaller
const smallerThanLg = breakpoints.smaller('lg') // only smaller than lg

import { useBreakpoints } from '@reause/core'

const breakpoints = useBreakpoints({
  mobile: 0, // optional
  tablet: 640,
  laptop: 1024,
  desktop: 1280,
})

// Can be 'mobile' or 'tablet' or 'laptop' or 'desktop'
const activeBreakpoint = breakpoints.active()

// true or false
const laptop = breakpoints.between('laptop', 'desktop')

Shortcut Methods

You can access breakpoints directly as properties on the returned object. These are reactive booleans.

const breakpoints = useBreakpoints({
  tablet: 640,
  laptop: 1024,
})

// Equivalent to breakpoints.greaterOrEqual('tablet') with min-width strategy
const isTablet = breakpoints.tablet

Strategy

The strategy option controls how the shortcut properties behave:

• min-width (default, mobile-first): breakpoints.lg is true when viewport is >= lg
• max-width (desktop-first): breakpoints.lg is true when viewport is < xl

const breakpoints = useBreakpoints(breakpointsTailwind, {
  strategy: 'max-width', // desktop-first
})

Available Methods

Method	Description
greaterOrEqual(k)	Reactive: viewport width >= breakpoint
greater(k)	Reactive: viewport width > breakpoint
smallerOrEqual(k)	Reactive: viewport width <= breakpoint
smaller(k)	Reactive: viewport width < breakpoint
between(a, b)	Reactive: viewport width between a and b
isGreaterOrEqual(k)	Non-reactive: returns boolean immediately
isGreater(k)	Non-reactive: returns boolean immediately
isSmallerOrEqual(k)	Non-reactive: returns boolean immediately
isSmaller(k)	Non-reactive: returns boolean immediately
isInBetween(a, b)	Non-reactive: returns boolean immediately
current()	Array of all matching breakpoints
active()	String of the current active breakpoint

Server Side Rendering and Nuxt

If you are using useBreakpoints with SSR enabled, then you need to specify which screen size you would like to render on the server and before hydration to avoid a hydration mismatch

import { breakpointsTailwind, useBreakpoints } from '@reause/core'

const breakpoints = useBreakpoints(breakpointsTailwind, {
  ssrWidth: 768 // Will enable SSR mode and render like if the screen was 768px wide
})

Alternatively you can set this up globally for your app using SSRWidthProvider: every useBreakpoints below the provider renders against the provided width, so a per-hook ssrWidth is only needed to override it.

import { SSRWidthProvider } from '@reause/core'

<SSRWidthProvider width={768}>
  <App />
</SSRWidthProvider>

Presets

• Tailwind: breakpointsTailwind
• Bootstrap v5: breakpointsBootstrapV5
• Vuetify v2: breakpointsVuetifyV2 (deprecated: breakpointsVuetify)
• Vuetify v3: breakpointsVuetifyV3
• Ant Design: breakpointsAntDesign
• Quasar v2: breakpointsQuasar
• Sematic: breakpointsSematic
• Master CSS: breakpointsMasterCss
• Prime Flex: breakpointsPrimeFlex
• ElementUI / ElementPlus: breakpointsElement

Breakpoint presets are standalone exported objects (they are not returned by useBreakpoints), so import the preset you need explicitly:

import { breakpointsTailwind } from '@reause/core'
// and so on

Type Declarations

Toggle

export type Breakpoints<K extends string = string> = Record<K, number | string>

export interface UseBreakpointsOptions extends ConfigurableWindow {
    strategy?: 'min-width' | 'max-width';
    ssrWidth?: number;
}

export type UseBreakpointReturn<K extends string = string> = Record<K, boolean> & {
    greaterOrEqual: (k: K) => boolean;
    smallerOrEqual: (k: K) => boolean;
    greater: (k: K) => boolean;
    smaller: (k: K) => boolean;
    between: (a: K, b: K) => boolean;
    isGreater: (k: K) => boolean;
    isGreaterOrEqual: (k: K) => boolean;
    isSmaller: (k: K) => boolean;
    isSmallerOrEqual: (k: K) => boolean;
    isInBetween: (a: K, b: K) => boolean;
    current: () => K[];
    active: () => K | '';
}

export const breakpointsTailwind

export const breakpointsBootstrapV5

export const breakpointsVuetifyV2

export const breakpointsVuetifyV3

export const breakpointsVuetify

export const breakpointsAntDesign

export const breakpointsQuasar

export const breakpointsSematic

export const breakpointsMasterCss

export const breakpointsPrimeFlex

export const breakpointsElement

export function useBreakpoints<K extends string>(breakpoints: Breakpoints<K>, options?: UseBreakpointsOptions): UseBreakpointReturn<K>

Source

Source · Demo · VueUse

Contributors

Changelog

v0.1.0 on

dbc31 - feat(core): consume the global SSR width in useMediaQuery and useBreakpoints (#849)

3554b - fix(core): resolve useBreakpoints audit findings (#527)

e4920 - feat(core): add useBreakpoints (#85)