{"id":26690776,"url":"https://github.com/d6u/react-container-query","last_synced_at":"2025-03-26T16:01:04.842Z","repository":{"id":40975992,"uuid":"48403708","full_name":"react-container-query/react-container-query","owner":"react-container-query","description":":package: Modular responsive component","archived":false,"fork":false,"pushed_at":"2023-09-14T19:07:39.000Z","size":3907,"stargazers_count":893,"open_issues_count":21,"forks_count":48,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-03-26T09:03:53.700Z","etag":null,"topics":["browser","container-queries","element-queries","react","responsive","responsive-layout"],"latest_commit_sha":null,"homepage":"http://react-container-query.github.io/react-container-query/","language":"JavaScript","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/react-container-query.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2015-12-22T01:40:14.000Z","updated_at":"2025-03-25T11:42:17.000Z","dependencies_parsed_at":"2024-04-17T18:08:36.166Z","dependency_job_id":null,"html_url":"https://github.com/react-container-query/react-container-query","commit_stats":{"total_commits":234,"total_committers":18,"mean_commits":13.0,"dds":"0.24786324786324787","last_synced_commit":"fae1d7b3d327db0eae1fd4c8eac97b074ea47d1a"},"previous_names":["d6u/react-container-query"],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/react-container-query%2Freact-container-query","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/react-container-query%2Freact-container-query/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/react-container-query%2Freact-container-query/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/react-container-query%2Freact-container-query/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/react-container-query","download_url":"https://codeload.github.com/react-container-query/react-container-query/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245689494,"owners_count":20656416,"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":["browser","container-queries","element-queries","react","responsive","responsive-layout"],"created_at":"2025-03-26T16:00:37.783Z","updated_at":"2025-03-26T16:01:04.815Z","avatar_url":"https://github.com/react-container-query.png","language":"JavaScript","readme":"# React Container Query\n\n**True modularity in styling responsive component.**\n\n[![npm version](https://badge.fury.io/js/react-container-query.svg)](https://badge.fury.io/js/react-container-query)\n[![Circle CI](https://circleci.com/gh/react-container-query/react-container-query/tree/master.svg?style=svg)](https://circleci.com/gh/react-container-query/react-container-query/tree/master)\n[![Build Status](https://saucelabs.com/buildstatus/react-cq)](https://saucelabs.com/beta/builds/de7d8039f4e5417399ec27c39036c1b8)\n[![codecov](https://codecov.io/gh/react-container-query/react-container-query/branch/master/graph/badge.svg)](https://codecov.io/gh/react-container-query/react-container-query)\n\n[![Build Status](https://saucelabs.com/browser-matrix/react-cq.svg)](https://saucelabs.com/beta/builds/de7d8039f4e5417399ec27c39036c1b8)\n\n## Installation\n\n```sh\nnpm i -D react-container-query\n```\n\n## Disclaimer\n\nThis code in this repository is provided under an open source license. It's provided by the individuals who contribute to the project in their personal capacity, not by any of their employers.\n\n## API\n\n### useContainerQuery(query, initialSize?)\n\n\u003e Compare the hook style code with the original example from https://github.com/react-container-query/react-container-query#containerquery-queryquery-initialsizewidth-height \n\n#### Hook Example 1 - Queries against a native DOM element as the container\n\n- Native DOM element refers to `div`, `span`, etc.\n\n```jsx\nimport React from 'react';\nimport { useContainerQuery } from 'react-container-query';\n\nconst query = {\n  'width-between-400-and-599': {\n    minWidth: 400,\n    maxWidth: 599,\n  },\n  'width-larger-than-600': {\n    minWidth: 600,\n  },\n};\n\nconst MyComponent = () =\u003e {\n  const [params, containerRef] = useContainerQuery(query);\n  return \u003cdiv ref={containerRef} className={classnames(params)}\u003ethe box\u003c/div\u003e;\n};\n```\n\n#### Hook Example 2 - Usage for a React component as the container - React.forwardRef\n\n- If the container element we want to measure is a React component, and since we can't measure the size of React component itself, we can use `React.forwardRef`. \n- The container React component must then forward the `ref` and set it on the actual native DOM element it renders (e.g, `div`, `span`, etc) - as seen in th example below\n\n\n```jsx\nimport React from 'react';\nimport { useContainerQuery } from 'react-container-query';\n\nconst query = {\n  'width-between-400-and-599': {\n    minWidth: 400,\n    maxWidth: 599,\n  },\n  'width-larger-than-600': {\n    minWidth: 600,\n  },\n};\n\nconst MyCustomWrapper = React.forwardRef((props, ref) =\u003e {\n  // MyCustomWrapper really renders a div which wraps the children. \n  // Setting the ref on it allows container query to measure its size.\n  return \u003cdiv ref={ref}\u003e{props.children}\u003c/div\u003e\n});\n\nconst MyComponent = () =\u003e {\n  const [params, containerRef] = useContainerQuery(query);\n  return \u003cMyCustomWrapper ref={containerRef} className={classnames(params)}\u003ethe box\u003c/div\u003e;\n};\n```\n\n- In this example, `\u003cMyCustomWrapper /\u003e` would forward the `containerRef` and set it on the `div` element it is using to wrap the children.\n\n### `\u003cContainerQuery query={query} initialSize?={{width?, height?}}\u003e`\n\n```jsx\nimport React, {Component} from 'react';\nimport {render} from 'react-dom';\nimport {ContainerQuery} from 'react-container-query';\nimport classnames from 'classnames';\n\nconst query = {\n  'width-between-400-and-599': {\n    minWidth: 400,\n    maxWidth: 599\n  },\n  'width-larger-than-600': {\n    minWidth: 600,\n  }\n};\n\nfunction MyComponent() {\n  /**\n   * `params` in the children function will look like\n   * {\n   *   'width-between-400-and-599': true,\n   *   'width-larger-than-600': false\n   * }\n   */\n  return (\n    \u003cContainerQuery query={query}\u003e\n      {(params) =\u003e (\n        \u003cdiv className={classnames(params)}\u003ethe box\u003c/div\u003e\n      )}\n    \u003c/ContainerQuery\u003e\n  );\n};\n\n/**\n * This will generate following HTML:\n * \u003cdiv class=\"width-between-400-and-599\"\u003e\u003c/div\u003e\n */\n\nrender(\u003cMyComponent/\u003e, document.getElementById('app'));\n```\n\n#### properties\n\n- `props.children`\n\n  Must be a function to return a single or an array of React elements. The function will be invoked with `params`, which is a key-value pair where keys are class names, values are booleans to indicate if that class name's constraints are all satisfied.\n\n- `props.query`\n\n  \"query\" is key-value pairs where keys are the class names that will be applied to container element when all constraints are met. The values are the constraints.\n\n- `props.initialSize?` (optional)\n\n  `initialSize` is an object with optional `width` or `height` property. Because the limitation on how size is computed based on underlying element, in the initial rendering pass, we don't have the size info (because element must be in the DOM have a valid size). At this time `initialSize` will be used as the size of the element.\n\n### `applyContainerQuery(Component, query, initialSize?) -\u003e ReactComponent`\n\n```jsx\nimport React, {Component} from 'react';\nimport {render} from 'react-dom';\nimport {applyContainerQuery} from 'react-container-query';\nimport classnames from 'classnames';\n\nconst query = {\n  'width-between-400-and-599': {\n    minWidth: 400,\n    maxWidth: 599\n  },\n  'width-larger-than-600': {\n    minWidth: 600,\n  }\n};\n\nclass Container extends Component {\n  render() {\n    /**\n     * `this.props.containerQuery` will look like\n     * {\n     *   'width-between-400-and-599': true,\n     *   'width-larger-than-600': false\n     * }\n     */\n    return \u003cdiv className={classnames(this.props.containerQuery)}\u003ethe box\u003c/div\u003e;\n  }\n}\n\nconst App = applyContainerQuery(Container, query)\n\n/**\n * This will generate following HTML:\n * \u003cdiv class=\"width-between-400-and-599\"\u003e\u003c/div\u003e\n */\n\nrender(\u003cApp/\u003e, document.getElementById('app'));\n```\n\nThis is a very similar to `\u003cContainerQuery/\u003e`, except it's higher order component style. You don't have to use them together.\n\n## Why\n\nModularity is the heart of component based UI. With most JavaScript modularized, CSS failed to catch up. When developing a responsive web page, we use media queries to toggle styles based on the size of the viewport. This creates problems when creating component level styles. The same component will behave differently when it is placed in different locations on a page. It seriously breaks the modularity of a component. We need components to be responsive and independent of viewport sizes.\n\n## What is container query\n\nContainer query is a work in process CSS feature. \"Container queries allow an author to control styling based on the size of a containing element rather than the size of the user’s viewport.\" (from [Container Query](http://responsiveimagescg.github.io/container-queries/)). [Container Queries: Once More Unto the Breach](http://alistapart.com/article/container-queries-once-more-unto-the-breach) is the inspiration of this repo.\n\nWith below CSS, `.box` will be blue when `.container` is wider than 600px, green when width between 400px and 599px, and red for the rest of time.\n\n```css\n.box {\n  background-color: red;\n}\n\n.container:media(min-width: 400px) {\n  .box {\n    background-color: green;\n  }\n}\n\n.container:media(min-width: 600px) {\n  .box {\n    background-color: blue;\n  }\n}\n```\n\n_Note: This library does *not* provide these CSS features._\n\n## Demo\n\nCheckout CodePen\n\n- Adjustable Sidebar http://codepen.io/daiweilu/pen/wMrrZM\n- Responsive Component Layout https://codepen.io/daiweilu/pen/EXWRqx\n\nYou can also check out [examples directory](./examples).\n\n## Performance\n\nreact-container-query is using [element-resize-detector](https://www.npmjs.com/package/element-resize-detector) in mainstream browsers and [ResizeObserver](https://developers.google.com/web/updates/2016/10/resizeobserver) in cutting edge browsers. It's completely event based, so no excessive code runs if no changes on element sizes.\n","funding_links":[],"categories":["Code Design","Uncategorized"],"sub_categories":["CSS / Style","Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd6u%2Freact-container-query","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fd6u%2Freact-container-query","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd6u%2Freact-container-query/lists"}