npm install --save react-gracefully

Overview

A library for responsively and gracefully rendering client and server side React.

react-gracefully exposes Express Middleware and the GraceProvider React provider component that allows devices, breakpoints and window to be configured client and server side.

Additionally, react-gracefully exposes the useGrace React hook and Show and Hide React components to allow React code to be responsively and gracefully rendered client and server side.

Installation

react-gracefully can be installed with npm or yarn.

npm install --save react-gracefully

or

yarn add react-gracefully

Usage

useGrace hook

react-gracefully exposes the useGrace React hook to get access to devices, breakpoints and window details.

Devices

Here is an example of how to use the useGrace hook to access device details.

import React from 'react';
import { useGrace } from 'react-gracefully';

export const Page = () => {
  const { is } = useGrace();
  const isMobile = is.mobile();
  const isTablet = is.tablet();
  const isDesktop = is.tablet();
  const isAndroid = is.device('android');
  return (
    <div>
      {isAndroid && <h2>Android Title</h2>}
      {isMobile && <h2>Mobile Title</h2>}
      {(isTablet || isDesktop) && <h1>Tablet or Desktop Title</h1>}
    </div>
  );
};

Breakpoints

Here is an example of how to use the useGrace hook to access breakpoint details.

import React from 'react';
import { useGrace } from 'react-gracefully';

export const Page = () => {
  const { is } = useGrace();
  const isAboveSmall = is.above.breakpoint('sm');
  const isBelowLarge = is.below.breakpoint('lg');
  const isMedium = is.current.breakpoint('md');
  return <div>{isAboveSmall && isBelowLarge && isMedium && <h2>Medium Title</h2>}</div>;
};

Window

Here is an example of how to use the useGrace hook to access window details.

import React from 'react';
import { useGrace } from 'react-gracefully';

export const Page = () => {
  const { is } = useGrace();
  const isWindowHeightAbove2em = is.above.window.height('2em');
  const isWindowWidthBelow500px = is.below.window.width('500px');
  const isLandscape = is.current.window.landscape();
  return (
    <div>{isWindowHeightAbove2em && isWindowWidthBelow500px && isLandscape && <h2>Landscape Medium Title</h2>}</div>
  );
};

Components

react-gracefully exposes a number of components. These components can be used to setup the configuration or show or hide content server side.

Show component

The Show component can be used to show content for specific breakpoints, devices or window orientation. Since it uses media queries under the hood all content is returned from the server to the client and then hidden or shown using css. This means it can be used effectively in server side rendered apps such as Next.js.

import React from 'react';
import { Show } from 'react-gracefully';

export const Page = () => {
  return (
    <div>
      <Show devices={['mobile']}>
        <h2>Mobile Title</h2>
      </Show>
      <Show devices={['tablet', 'desktop']}>
        <h1>Tablet or Desktop Title</h1>
      </Show>
    </div>
  );
};

Hide component

The Hide component can be used to hide content for specific breakpoints, devices or window orientation. Since it uses media queries under the hood all content is returned from the server to the client and then hidden or shown using css. This means it can be used effectively in server side rendered apps such as Next.js.

import React from 'react';
import { Hide } from 'react-gracefully';

export const Page = () => {
  return (
    <div>
      <Hide devices={['mobile']}>
        <h1>Tablet or Desktop Title</h1>
      </Hide>
      <Hide devices={['tablet', 'desktop']}>
        <h2>Mobile Title</h2>
      </Hide>
    </div>
  );
};

GraceProvider component

The GraceProvider component is used to scope and configure use-gracefully for the app. It allows custom breakpoints and/or devices to be configured.

import React from 'react';
import { GraceProvider } from 'react-gracefully';

export const App = () => {
  const breakpoints: Breakpoints = {
    sm: {
      max: '500px'
    },
    md: {
      min: '500px',
      max: '1000px'
    },
    lg: {
      min: '1000px'
    }
  };
  const devices = ['mobile', 'ios', 'android', 'tablet', 'desktop'];
  return (
    <GraceProvider breakpoints={breakpoints} devices={devices}>
      <Router />
    </GraceProvider>
  );
};

Express Middleware

Default (UserAgent)

The react-gracefully express middleware by default will use the user-agent to sniff the current device type.

import express from 'express';
import grace from 'react-gracefully';

const app = express();
app.use(grace.express());

Custom (Headers)

Optionally, react-gracefully express middleware can be configured to check custom headers for the current device type.

import express from 'express';
import grace, { Config, Headers } from 'react-gracefully';

const app = express();
const config: Config = {
  devices: {
    mobile: (headers: Headers) => headers['x-device-type'] === 'mobile',
    tablet: (headers: Headers) => headers['x-device-type'] === 'tablet',
    desktop: (headers: Headers) => headers['x-device-type'] === 'desktop',
    ios: (headers: Headers) => headers['x-device-type'] === 'ios',
    android: (headers: Headers) => headers['x-device-type'] === 'android'
  }
};
app.use(grace.express(config));

Copyright 🦢

MIT