{"id":13422450,"url":"https://github.com/jmlweb/reactponsive","last_synced_at":"2025-05-13T19:32:00.119Z","repository":{"id":57348435,"uuid":"178738376","full_name":"jmlweb/reactponsive","owner":"jmlweb","description":"Responsive components and Hooks ⚒ for your favorite framework ⚛️","archived":false,"fork":false,"pushed_at":"2020-10-24T18:43:12.000Z","size":2722,"stargazers_count":14,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2024-04-25T10:43:12.882Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://jmlweb.github.io/reactponsive","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jmlweb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-31T20:25:35.000Z","updated_at":"2023-11-09T19:33:13.000Z","dependencies_parsed_at":"2022-08-31T18:01:04.386Z","dependency_job_id":null,"html_url":"https://github.com/jmlweb/reactponsive","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmlweb%2Freactponsive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmlweb%2Freactponsive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmlweb%2Freactponsive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmlweb%2Freactponsive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jmlweb","download_url":"https://codeload.github.com/jmlweb/reactponsive/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225254360,"owners_count":17445169,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T23:00:45.248Z","updated_at":"2024-11-18T21:31:59.436Z","avatar_url":"https://github.com/jmlweb.png","language":"TypeScript","readme":"# 🔫 ReactPonsive\n\n\u003e Responsive components and Hooks ⚒ for your favorite framework ⚛️ [http://jmlweb.github.io/reactponsive](http://jmlweb.github.io/reactponsive)\n\n[![Last Commit][last-commit-badge]][last-commit]\n[![Travis][build-badge]][build]\n[![npm package][npm-badge]][npm]\n[![Coveralls][coveralls-badge]][coveralls]\n[![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/jmlweb/reactponsive.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/jmlweb/reactponsive/context:javascript)\n[![Watch on GitHub][github-watch-badge]][github-watch]\n[![Star on GitHub][github-star-badge]][github-star]\n[![Tweet][twitter-badge]][twitter]\n\n[last-commit-badge]: https://img.shields.io/github/last-commit/jmlweb/reactponsive.svg\n[last-commit]: https://github.com/jmlweb/reactponsive\n[build-badge]: https://img.shields.io/travis/jmlweb/reactponsive/master.png?style=flat-square\n[build]: https://travis-ci.org/jmlweb/reactponsive\n[npm-badge]: https://img.shields.io/npm/v/reactponsive.png?style=flat-square\n[npm]: https://www.npmjs.org/package/reactponsive\n[coveralls-badge]: https://img.shields.io/coveralls/jmlweb/reactponsive/master.png?style=flat-square\n[coveralls]: https://coveralls.io/github/jmlweb/reactponsive\n[github-watch-badge]: https://img.shields.io/github/watchers/jmlweb/reactponsive.svg?style=social\n[github-watch]: https://github.com/jmlweb/reactponsive/watchers\n[github-star-badge]: https://img.shields.io/github/stars/jmlweb/reactponsive.svg?style=social\n[github-star]: https://github.com/jmlweb/reactponsive/stargazers\n[twitter]: https://twitter.com/intent/tweet?text=Reactponsive:%20Responsive%20hooks%20and%20components%20for%20React%20⚛️:%20https%3A%2F%2Fgithub.com%2Fjmlweb%2Freactponsive\n[twitter-badge]: https://img.shields.io/twitter/url/https/github.com/testing-library/dom-testing-library.svg?style=social\n\n- [Principles](#Principles)\n- [Installation](#Installation)\n- [Requirements](#Requirements)\n- [API](#API)\n  - [Provider](#Provider)\n  - [useInfo](#useInfo)\n  - [useToggler](#useToggler)\n  - [useMapper](#useMapper)\n  - [useFilter](#useFilter)\n  - [Toggler](#Toggler)\n  - [Mapper](#Mapper)\n  - [Filter](#Filter)\n  - [useAlias](#useAlias)\n\n## Principles\n\n- 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...).\n- Works with **native MatchMedia API** and receives **[valid Media Query Strings](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries)** as arguments.\n- Supports the use of **\"alias\"** (`{ tablet: '(min-width: 768px)' }`).\n- Is **fast** and performant, and **only updates** the connected components **when needed**.\n- Includes a **Jest mock for MatchMedia** API which supports updating the breakpoints matches.\n\n## Installation\n\n```sh\nnpm install reactponsive\n#or\nyarn add reactponsive\n```\n\n## Requirements\n\n- ReactPonsive **works only with hooks** for performance reasons, so you will need **React \u003e= 16.8** (or any older experimental version supporting hooks)\n- You will also need **@testing-library/react-hooks** and **react-test-renderer**\n\n## API\n\n### Provider\n\nThis is where all the magic take place. **You must include this component before using the rest of the components and hooks.**\n\nThe use of `alias` is supported with the same property to keep your mind sane 😸.\n\nThis property is an object, where each key refers to the alias name, and the value to a valid [media query string](https://developer.mozilla.org/es/docs/CSS/Media_queries).\n\n```jsx\nimport { Provider } from \"reactponsive\";\nimport MyAppComponent from \"./MyAppComponent\";\n\nconst alias = {\n  tablet: \"(min-width: 768px)\",\n  desktop: \"(min-width: 1024px)\",\n  hd: \"(-webkit-min-device-pixel-ratio: 1.25), (min-resolution: 120dpi)\",\n  darkMode: \"(prefers-color-scheme: dark)\",\n  supportsHover: \"(hover: hover)\",\n  noMotion: \"(prefers-reduced-motion: reduce)\"\n};\nconst App = () =\u003e (\n  \u003cAliasProvider alias={alias}\u003e\n    \u003cMyAppComponent /\u003e\n  \u003c/AliasProvider\u003e\n);\n\nexport default App;\n```\n\n### useInfo\n\nIt receives an array representing valid query strings or alias, and returns useful info about them:\n\n```jsx\nimport { useInfo } from \"reactponsive\";\n\nconst props = useReactPonsive([\n  \"tablet\",\n  \"(min-width: 1024px)\",\n  \"(min-width: 1280px)\"\n]);\n```\n\nIt returns:\n\n- **first**: The first matching query string or alias or `undefined`.\n- **last**: The last matching query string or alias or `undefined`.\n- **matches**: An object, having the query strings or aliases as properties, and the results of the match as values.\n- **passes**: An array containing only the matching query strings or aliases.\n\n```js\n{\n  first: 'tablet',\n  last: '(min-width: 1024px)',\n  matches: {\n  \ttablet: true,\n  \t'(min-width: 1024px)': true,\n  \t'(min-width: 1280px)': false,\n  },\n  passes: ['tablet', '(min-width: 1024px)'],\n}\n```\n\n### useToggler\n\nIt receives a valid query string or alias, or an array of them. It returns true if **any** of the media queries matches.\n\nYou can enable \"strict mode\" with a second boolean argument. Then, it returns true if **all** of the media queries match.\n\n```\n(string | string[], boolean?) =\u003e boolean;\n```\n\n```jsx\nimport { useToggler } from \"reactponsive\";\n\nconst value1 = useToggler(\"tablet\"); // true if matches\nconst value2 = useToggler([\"tablet\", \"desktop\"]); // true if any match\nconst value3 = useToggler([\"tablet\", \"desktop\"], true); // true if both match\n```\n\n### useMapper\n\nIt receives an object with the media query strings as keys and returns the value corresponding to the last one that matches.\n\n```jsx\nimport { useMapper } from 'reactponsive';\n\nconst component = useMapper({\n  default: DefaultComponent,\n  tablet: TabletComponent,\n  (min-width: 1024px): DesktopComponent,\n}); // DesktopComponent (or the last that matches or DefaultComponent if no one matches)\n```\n\nIt returns the first one when providing \"first\" as the second argument.\n\n```jsx\nimport { useMapper } from 'reactponsive';\n\nconst value = useMapper({\n  default: DefaultComponent,\n  tablet: TabletComponent,\n  (min-width: 1024px): DesktopComponent,\n}, 'first'); // TabletComponent (or DefaultComponent if it doesn't match)\n```\n\n### useFilter\n\nIt receives an object with the media query strings as keys and returns an array with all the values that match.\n\n```jsx\nimport { useFilter } from \"reactponsive\";\n\nconst modulesToStart = useFilter({\n  darkMode: darkModeModule,\n  supportsHover: hoverModule\n});\n\nuseEffect(() =\u003e {\n  // let's suppose we want to dispatch the start action of each module\n  // when the media query matches and the module hasn't been started yet\n  modulesToStart.forEach(module =\u003e {\n    if (!module.started) {\n      module.start();\n    }\n  });\n}, [modulesToStart]);\n```\n\n### Toggler\n\nOnly renders the children when the query string(s) match(es)\n\nIt supports a `strict` prop. When it's true, only renders the children when all the query strings match.\n\n```jsx\n\u003cToggler\n  mqs={[\n    \"tablet\",\n    \"(-webkit-min-device-pixel-ratio: 1.25), (min-resolution: 120dpi)\"\n  ]}\n\u003e\n  \u003cdiv\u003eThis will render when any of the query strings match\u003c/div\u003e\n\u003c/Toggler\u003e\n```\n\n```jsx\n\u003cToggler\n  mqs={[\n    \"tablet\",\n    \"(-webkit-min-device-pixel-ratio: 1.25), (min-resolution: 120dpi)\"\n  ]}\n  strict\n\u003e\n  \u003cdiv\u003eThis will render when all of the query strings match\u003c/div\u003e\n\u003c/Toggler\u003e\n```\n\n### Mapper\n\nRenders the last (by default) or first value defined in an object whose keys are media strings.\n\nIt is possible to pass a `default` key, and the value will render when no media query string match.\n\n```jsx\n\u003cMapper mqs={{\n  default: \u003cDefaultComponent /\u003e,\n  tablet: \u003cTabletComponent /\u003e,\n  (min-width: 1024px): \u003cDesktopComponent /\u003e,\n}}\u003e\n  \u003cdiv\u003eDesktopComponent or TabletComponent (the last which matches) or DefaultComponent if no one matches.\u003c/div\u003e\n\u003c/Mapper\u003e\n```\n\n```jsx\n\u003cMapper mqs={{\n  default: \u003cDefaultComponent /\u003e,\n  tablet: \u003cTabletComponent /\u003e,\n  (min-width: 1024px): \u003cDesktopComponent /\u003e,\n}} mode=\"first\"\u003e\n  \u003cdiv\u003eTablet Component if matches, or DefaultComponent if not.\u003c/div\u003e\n\u003c/Mapper\u003e\n```\n\n### Filter\n\nRenders all the matching elements defined in an object whose keys are media strings.\n\nIt is possible to pass a `default` key, and the value will render when no media query string match.\n\n```jsx\n\u003cFilter mqs={{\n  default: \u003cDefaultComponent /\u003e,\n  tablet: \u003cTabletComponent /\u003e,\n  (min-width: 1024px): \u003cDesktopComponent /\u003e,\n}} /\u003e\n```\n\n### useAlias\n\nYou'll rarely will need this, but it is possible to retrieve the `alias` you passed to the `Provider`\n\n```jsx\nimport { useAlias } from \"reactponsive\";\n\nconst alias = useAlias();\n```\n\n## Author\n\nJosé Manuel Lucas [@jmlweb](https://twitter.com/jmlweb)\n","funding_links":[],"categories":["Code Design"],"sub_categories":["CSS / Style"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmlweb%2Freactponsive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjmlweb%2Freactponsive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmlweb%2Freactponsive/lists"}