Home

Awesome

🔫 ReactPonsive

Responsive components and Hooks ⚒ for your favorite framework ⚛️ http://jmlweb.github.io/reactponsive

Last Commit Travis npm package Coveralls Language grade: JavaScript Watch on GitHub Star on GitHub Tweet

Principles

Installation

npm install reactponsive
#or
yarn add reactponsive

Requirements

API

Provider

This is where all the magic take place. You must include this component before using the rest of the components and hooks.

The use of alias is supported with the same property to keep your mind sane 😸.

This property is an object, where each key refers to the alias name, and the value to a valid media query string.

import { Provider } from "reactponsive";
import MyAppComponent from "./MyAppComponent";

const alias = {
  tablet: "(min-width: 768px)",
  desktop: "(min-width: 1024px)",
  hd: "(-webkit-min-device-pixel-ratio: 1.25), (min-resolution: 120dpi)",
  darkMode: "(prefers-color-scheme: dark)",
  supportsHover: "(hover: hover)",
  noMotion: "(prefers-reduced-motion: reduce)"
};
const App = () => (
  <AliasProvider alias={alias}>
    <MyAppComponent />
  </AliasProvider>
);

export default App;

useInfo

It receives an array representing valid query strings or alias, and returns useful info about them:

import { useInfo } from "reactponsive";

const props = useReactPonsive([
  "tablet",
  "(min-width: 1024px)",
  "(min-width: 1280px)"
]);

It returns:

{
  first: 'tablet',
  last: '(min-width: 1024px)',
  matches: {
  	tablet: true,
  	'(min-width: 1024px)': true,
  	'(min-width: 1280px)': false,
  },
  passes: ['tablet', '(min-width: 1024px)'],
}

useToggler

It receives a valid query string or alias, or an array of them. It returns true if any of the media queries matches.

You can enable "strict mode" with a second boolean argument. Then, it returns true if all of the media queries match.

(string | string[], boolean?) => boolean;
import { useToggler } from "reactponsive";

const value1 = useToggler("tablet"); // true if matches
const value2 = useToggler(["tablet", "desktop"]); // true if any match
const value3 = useToggler(["tablet", "desktop"], true); // true if both match

useMapper

It receives an object with the media query strings as keys and returns the value corresponding to the last one that matches.

import { useMapper } from 'reactponsive';

const component = useMapper({
  default: DefaultComponent,
  tablet: TabletComponent,
  (min-width: 1024px): DesktopComponent,
}); // DesktopComponent (or the last that matches or DefaultComponent if no one matches)

It returns the first one when providing "first" as the second argument.

import { useMapper } from 'reactponsive';

const value = useMapper({
  default: DefaultComponent,
  tablet: TabletComponent,
  (min-width: 1024px): DesktopComponent,
}, 'first'); // TabletComponent (or DefaultComponent if it doesn't match)

useFilter

It receives an object with the media query strings as keys and returns an array with all the values that match.

import { useFilter } from "reactponsive";

const modulesToStart = useFilter({
  darkMode: darkModeModule,
  supportsHover: hoverModule
});

useEffect(() => {
  // let's suppose we want to dispatch the start action of each module
  // when the media query matches and the module hasn't been started yet
  modulesToStart.forEach(module => {
    if (!module.started) {
      module.start();
    }
  });
}, [modulesToStart]);

Toggler

Only renders the children when the query string(s) match(es)

It supports a strict prop. When it's true, only renders the children when all the query strings match.

<Toggler
  mqs={[
    "tablet",
    "(-webkit-min-device-pixel-ratio: 1.25), (min-resolution: 120dpi)"
  ]}
>
  <div>This will render when any of the query strings match</div>
</Toggler>
<Toggler
  mqs={[
    "tablet",
    "(-webkit-min-device-pixel-ratio: 1.25), (min-resolution: 120dpi)"
  ]}
  strict
>
  <div>This will render when all of the query strings match</div>
</Toggler>

Mapper

Renders the last (by default) or first value defined in an object whose keys are media strings.

It is possible to pass a default key, and the value will render when no media query string match.

<Mapper mqs={{
  default: <DefaultComponent />,
  tablet: <TabletComponent />,
  (min-width: 1024px): <DesktopComponent />,
}}>
  <div>DesktopComponent or TabletComponent (the last which matches) or DefaultComponent if no one matches.</div>
</Mapper>
<Mapper mqs={{
  default: <DefaultComponent />,
  tablet: <TabletComponent />,
  (min-width: 1024px): <DesktopComponent />,
}} mode="first">
  <div>Tablet Component if matches, or DefaultComponent if not.</div>
</Mapper>

Filter

Renders all the matching elements defined in an object whose keys are media strings.

It is possible to pass a default key, and the value will render when no media query string match.

<Filter mqs={{
  default: <DefaultComponent />,
  tablet: <TabletComponent />,
  (min-width: 1024px): <DesktopComponent />,
}} />

useAlias

You'll rarely will need this, but it is possible to retrieve the alias you passed to the Provider

import { useAlias } from "reactponsive";

const alias = useAlias();

Author

José Manuel Lucas @jmlweb