Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub

gatsby-plugin-breakpoints

Gatsby plugin providing breakpoints using React Hooks

travis build travis build npm version NPM downloads dependencies status dev dependencies status

commitizen semantic-release prettier license

Install

npm i gatsby-plugin-breakpoints

or

yarn add gatsby-plugin-breakpoints

Include the plugin in your gatsby-config.js file :

/* gatsby-config.js */

module.exports = {
    plugins: ['gatsby-plugin-breakpoints'],
};

Usage

Functional Components

Import the useBreakpoint hook anywhere in your app.

This hook provides four default breakpoints as boolean :

name breakpoints
xs max-width: 320px
sm max-width: 720px
md max-width: 1024px
l max-width: 1536px
/* yourFunctionalComponentOrPage.js */

import { useBreakpoint } from 'gatsby-plugin-breakpoints';

import MobileOnlyComponent from './your/component/path';
// ...

const MyComponent = () => {
    const breakpoints = useBreakpoint();

    return (
        <AnyComponent>
            {/* Anything */}

            {/* <MobileOnlyComponent /> will only be displayed if max-width <= 320px  */}
            {breakpoints.xs ? <MobileOnlyComponent /> : null}
        </AnyComponent>
    );
};

export default MyComponent;

Class Components

Import the withBreakpoints Higher Order Component anywhere in your app.

This HOC adds a breakpoints props to your component, providing four default breakpoints as boolean :

name breakpoints
xs max-width: 320px
sm max-width: 720px
md max-width: 1024px
l max-width: 1536px
/* yourClassComponent.js */

import { withBreakpoints } from 'gatsby-plugin-breakpoints';

import MobileOnlyComponent from './your/component/path';
// ...

class Test extends React.Component {
    render() {
        const { breakpoints } = this.props;
        {
            /* <MobileOnlyComponent /> will only be displayed if max-width <= 320px  */
        }
        return breakpoints.xs ? (
            <MobileOnlyComponent />
        ) : (
            <div>Content hidden only on mobile</div>
        );
    }
}

export default withBreakpoints(Test);

Options

You can set your own queries like this :

// in gatsby-config.js

const myCustomQueries = {
    xs: '(max-width: 320px)',
    sm: '(max-width: 720px)',
    md: '(max-width: 1024px)',
    l: '(max-width: 1536px)',
    xl: ...,
    portrait: '(orientation: portrait)',
};

module.exports = {
    plugins: [
        {
            resolve: "gatsby-plugin-breakpoints",
            options: {
                queries: myCustomQueries,
            },
        },
    ],
}

Default values

const defaultQueries = {
    xs: '(max-width: 320px)',
    sm: '(max-width: 720px)',
    md: '(max-width: 1024px)',
    l: '(max-width: 1536px)',
};

Note (only for test)

If you need to import <BreakpointProvider /> for testing you can do it like so :

import { BreakpointProvider } from 'gatsby-plugin-breakpoints';

In case you need full context, you can import it too :

import { BreakpointContext } from 'gatsby-plugin-breakpoints';

Contributing

Contributions are welcome ! See contributing guidelines

License

MIT

Copyright (c) 2019 Jimmy Beldone

© 2024 Gatsby, Inc.