reactponsive

Responsive components and Hooks ⚒ for your favorite framework ⚛️

Monthly Downloads: 0

Programming language: TypeScript

License: MIT License

Tags: Code Design     CSS / Style    

Latest version: v0.0.4

README

🔫 ReactPonsive

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

• Principles
• Installation
• Requirements
• API
  • Provider
  • useInfo
  • useToggler
  • useMapper
  • useFilter
  • Toggler
  • Mapper
  • Filter
  • useAlias

Principles

• Intended for complex interfaces where the use of media queries in CSS is not enough (Displaying different headers on mobile/desktop, enhancing accesibility in your components if some flag is active, displaying charts only on desktop sizes...).
• Works with native MatchMedia API and receives valid Media Query Strings as arguments.
• Supports the use of "alias" ({ tablet: '(min-width: 768px)' }).
• Is fast and performant, and only updates the connected components when needed.
• Includes a Jest mock for MatchMedia API which supports updating the breakpoints matches.

Installation

npm install reactponsive
#or
yarn add reactponsive

Requirements

• ReactPonsive works only with hooks for performance reasons, so you will need React >= 16.8 (or any older experimental version supporting hooks)
• You will also need @testing-library/react-hooks and react-test-renderer

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: The first matching query string or alias or undefined.
• last: The last matching query string or alias or undefined.
• matches: An object, having the query strings or aliases as properties, and the results of the match as values.
• passes: An array containing only the matching query strings or aliases.

{
  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