Breakpoints

Breakpoints are user-defined key/value pairs that describe the boundaries of screen sizes. There’s no limit to the number of breakpoints; you can define as many as you want.

Register breakpoints

To register your breakpoints, create an object with any keys:

const breakpoints = {
    xs: 0,
    sm: 576,
    md: 768,
    lg: 992,
    xl: 1200,
    superLarge: 2000,
    tvLike: 4000
} as const

The first breakpoint must start with 0. This is required to simulate CSS cascading, e.g., everything below 576px (sm breakpoint) will resolve to xs breakpoint.

If you use TypeScript you need to override the library’s type:

type AppBreakpoints = typeof breakpoints

declare module 'react-native-unistyles' {
  export interface UnistylesBreakpoints extends AppBreakpoints {}
}

Finally, to register the breakpoints, call StyleSheet.configure:

import { StyleSheet } from 'react-native-unistyles'

StyleSheet.configure({
    breakpoints
})

To learn more, follow the configuration guide.

How to use breakpoints?

Any style can change based on breakpoints. To do this, change a value to an object:

const styles = StyleSheet.create(theme => ({
    container: {
        flex: 1,
        justifyContent: 'center',
        alignItems: 'center',
        backgroundColor: theme.colors.background,
        backgroundColor: {
            // your breakpoints
            xs: theme.colors.background,
            sm: theme.colors.barbie
        }
    },
    text: {
        color: theme.colors.typography
    }
}))

You can even use it with nested objects like transform, shadowOffset, or filter:

const styles = StyleSheet.create(theme => ({
    container: {
        flex: 1,
        justifyContent: 'center',
        alignItems: 'center',
        backgroundColor: {
            xs: theme.colors.background,
            sm: theme.colors.barbie
        },
        transform: [
            {
                translateX: 100
            },
            {
                scale: {
                    xs: 1.5,
                    xl: 0.9
                }
            }
        ]
    }
}))

Breakpoints are also available with variants and compound variants.

Built-in breakpoints `landscape` and `portrait`

Even if you don’t use custom breakpoints, you can still utilize Unistyles’ predefined breakpoints: portrait and landscape.

portrait is used when the screen height is greater than or equal to its width
landscape is used when the screen width is greater than its height

const styles = StyleSheet.create(theme => ({
    container: {
        flex: 1,
        justifyContent: 'center',
        alignItems: 'center',
        backgroundColor: {
            landscape: theme.colors.background,
            portrait: theme.colors.barbie
        }
    }
}))

Pixel/Point mode for native breakpoints

By default (nativeBreakpointsMode: 'pixels'), native breakpoints and mq are compared against UnistylesRuntime.screen, which is expressed in density-independent units (points on iOS, dp on Android). You can change this behavior by setting nativeBreakpointsMode to points in your configuration.

If nativeBreakpointsMode is set to points, the screen dimensions are additionally divided by UnistylesRuntime.pixelRatio before being compared with your breakpoints and mq.

Show/Hide your components based on breakpoints

In order to show or hide your components based on the screen size, you can leverage the mq utility and one of the two built-in components: Display and Hide.

import React from 'react'
import { Text } from 'react-native'
import { Display, Hide, mq } from 'react-native-unistyles'

const MyComponent = () => {
    return (
        <React.Fragment>
            <Display mq={mq.only.width(0, 400)}>
                <Text>This text is visible on small devices</Text>
            </Display>
            <Hide mq={mq.only.width(400)}>
                <Text>This text is hidden on big devices</Text>
            </Hide>
        </React.Fragment>
    )
}

You can also access your current breakpoint with UnistylesRuntime:

import { UnistylesRuntime } from 'react-native-unistyles'

// check the current breakpoint
export const CurrentBreakpoint = () => (
    <Text>
        Current breakpoint is {UnistylesRuntime.breakpoint}
    </Text>
)

Get registered breakpoints

Access your registered breakpoints object with UnistylesRuntime:

import { UnistylesRuntime } from 'react-native-unistyles'

// check the registered breakpoints
export const RegisteredBreakpoints = () => (
    <Text>
        My registered breakpoint are {JSON.stringify(UnistylesRuntime.breakpoints)}
    </Text>
)