{"id":15637131,"url":"https://github.com/alexkrolick/use-conditional-effect","last_synced_at":"2025-04-13T09:24:31.355Z","repository":{"id":46936209,"uuid":"189711181","full_name":"alexkrolick/use-conditional-effect","owner":"alexkrolick","description":"React.useEffect, except you can pass a comparison function.","archived":false,"fork":false,"pushed_at":"2022-12-09T04:43:55.000Z","size":2221,"stargazers_count":111,"open_issues_count":16,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-10T13:12:37.459Z","etag":null,"topics":["hooks","react","useeffect"],"latest_commit_sha":null,"homepage":"https://npm.im/use-conditional-effect","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/alexkrolick.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-06-01T08:52:19.000Z","updated_at":"2023-04-28T11:43:59.000Z","dependencies_parsed_at":"2023-01-25T16:16:34.607Z","dependency_job_id":null,"html_url":"https://github.com/alexkrolick/use-conditional-effect","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexkrolick%2Fuse-conditional-effect","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexkrolick%2Fuse-conditional-effect/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexkrolick%2Fuse-conditional-effect/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexkrolick%2Fuse-conditional-effect/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexkrolick","download_url":"https://codeload.github.com/alexkrolick/use-conditional-effect/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248689846,"owners_count":21146015,"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":["hooks","react","useeffect"],"created_at":"2024-10-03T11:10:22.651Z","updated_at":"2025-04-13T09:24:31.327Z","avatar_url":"https://github.com/alexkrolick.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003ch1\u003euse-conditional-effect 🎲\u003c/h1\u003e\n\n\u003cp\u003e\n\nIt's React's [useEffect][useeffect] hook, except you can pass a comparison\nfunction.\n\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n\u003chr /\u003e\n\n[![Build Status][build-badge]][build]\n[![Code Coverage][coverage-badge]][coverage]\n[![version][version-badge]][package] [![downloads][downloads-badge]][npmtrends]\n[![MIT License][license-badge]][license]\n\n[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)][contributors]\n[![PRs Welcome][prs-badge]][prs] [![Code of Conduct][coc-badge]][coc]\n\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## The problem\n\nReact's built-in `useEffect` hook has a second argument called the \"dependencies\narray\" and it allows you to decide when React will call your effect callback.\nReact will do a comparison between each of the values (using `Object.is`, which\nis similar to `===`) to determine whether your effect callback should be called.\n\nThe idea behind the dependencies array is that the identity of the items in the\narray will tell you when to run the effect.\n\nThere are several cases where object identity is not a good choice for\ntriggering effects:\n\n- You want to call a callback function, which may change identity, _when certain\n  things change_ (not when the function itself changes). Sometimes you can\n  memoize the function with useCallback, or assume someone else has done that,\n  but doing so couples your effect condition to external code.\n- The values you need to compare require custom comparison (like a\n  deep/recursive equality check).\n\nHere's an example situation:\n\n```jsx\nfunction Query({query, variables}) {\n  // some code...\n\n  // Who knows if this is a stable reference!\n  const getQueryResult = useMyGraphQlLibrary()\n\n  React.useEffect(\n    () =\u003e {\n      getQueryResult(query, variables)\n    },\n    // ⚠️ PROBLEMS!\n    // - variables is a new object every render but we only want\n    //   to run the effect when the username property changes\n    // - getQueryResult might change but we don't want to run the\n    //   effect when that happens\n    [query, variables, getQueryResult],\n  )\n\n  return \u003cdiv\u003e{/* awesome UI here */}\u003c/div\u003e\n}\n\nfunction QueryPageThing({username}) {\n  const query = `\n    query getUserData($username: String!) {\n      user(login: $username) {\n        name\n      }\n    }\n  `\n  const variables = {username}\n  // poof! Every render `variables` will be a new object!\n  return \u003cQuery query={query} variables={variables} /\u003e\n}\n```\n\n\u003e **Note**\n\u003e\n\u003e You could also solve the first problem if the `QueryPageThing` created the\n\u003e variables object like this:\n\u003e `const variables = React.useMemo(() =\u003e ({username}), [username])`. Then you\n\u003e wouldn't need this package. But sometimes you're writing a custom hook and you\n\u003e don't have control on what kinds of things people are passing you (or you want\n\u003e to give them a nice ergonomic API that can handle new objects every render).\n\u003e\n\u003e In the second case, technically you don't have to add the callback to the\n\u003e dependencies array. But the [exhaustive-deps][exhaustive-deps-lint] ESLint\n\u003e rule automatically will add it unless you disable the rule.\n\n## This solution\n\nThis is a replacement for `React.useEffect` that accepts a comparison function\nin addition to the dependencies array. The comparison function gets the previous\nvalue of the dependencies as well as the current value, and the effect only runs\nif it returns true. Additionally, dependencies doesn't have to be an array, it\ncan be an object or any other value.\n\n## Table of Contents\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Compatibility with `React.useEffect`](#compatibility-with-reactuseeffect)\n- [Other Solutions](#other-solutions)\n- [LICENSE](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Installation\n\nThis module is distributed via [npm][npm] which is bundled with [node][node] and\nshould be installed as one of your project's `dependencies`:\n\n```\nnpm install --save use-conditional-effect\n```\n\n## Usage\n\nYou use it in place of `React.useEffect`.\n\nExample:\n\n```jsx\nimport React from 'react'\nimport ReactDOM from 'react-dom'\nimport useConditionalEffect from 'use-conditional-effect'\n\nfunction Query({query, variables}) {\n  // Example: using some external library's method\n  const getQueryResult = useMyGraphQlLibrary()\n\n  // We don't need to use an array for the second argument\n  // The third argument is the comparison function\n  useConditionalEffect(\n    () =\u003e {\n      getQueryResult(query, variables)\n    },\n    {query, variables, getQueryResult},\n    (current, previous = {}) =\u003e {\n      if (\n        current.query !== previous.query ||\n        current.variables.username !== previous.variables.username\n      ) {\n        return true\n      }\n    },\n  )\n\n  return \u003cdiv\u003e{/* awesome UI here */}\u003c/div\u003e\n}\n```\n\n### Compatibility with `React.useEffect`\n\n- If you don't pass the third argument, the comparison function defaults to the\n  same comparison function as useEffect (thus, the second argument has to be an\n  array in this case).\n- If you don't pass the second or third arguments, the effect always runs (same\n  as useEffect).\n\n## Other Solutions\n\n- https://github.com/kentcdodds/use-deep-compare-effect\n\n## LICENSE\n\nMIT\n\n[npm]: https://www.npmjs.com/\n[node]: https://nodejs.org\n[build-badge]:\n  https://img.shields.io/travis/alexkrolick/use-conditional-effect.svg?style=flat-square\n[build]: https://travis-ci.org/alexkrolick/use-conditional-effect\n[coverage-badge]:\n  https://img.shields.io/codecov/c/github/alexkrolick/use-conditional-effect.svg?style=flat-square\n[coverage]: https://codecov.io/github/alexkrolick/use-conditional-effect\n[version-badge]:\n  https://img.shields.io/npm/v/use-conditional-effect.svg?style=flat-square\n[package]: https://www.npmjs.com/package/use-conditional-effect\n[downloads-badge]:\n  https://img.shields.io/npm/dm/use-conditional-effect.svg?style=flat-square\n[npmtrends]: http://www.npmtrends.com/use-conditional-effect\n[license-badge]:\n  https://img.shields.io/npm/l/use-conditional-effect.svg?style=flat-square\n[license]:\n  https://github.com/alexkrolick/use-conditional-effect/blob/master/LICENSE\n[prs-badge]:\n  https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square\n[prs]: http://makeapullrequest.com\n[donate-badge]:\n  https://img.shields.io/badge/$-support-green.svg?style=flat-square\n[coc-badge]:\n  https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square\n[coc]:\n  https://github.com/alexkrolick/use-conditional-effect/blob/master/other/CODE_OF_CONDUCT.md\n[github-watch-badge]:\n  https://img.shields.io/github/watchers/alexkrolick/use-conditional-effect.svg?style=social\n[github-watch]: https://github.com/alexkrolick/use-conditional-effect/watchers\n[github-star-badge]:\n  https://img.shields.io/github/stars/alexkrolick/use-conditional-effect.svg?style=social\n[github-star]: https://github.com/alexkrolick/use-conditional-effect/stargazers\n[twitter]:\n  https://twitter.com/intent/tweet?text=Check%20out%20use-conditional-effect%20by%20%40alexkrolick%20https%3A%2F%2Fgithub.com%2Falexkrolick%2Fuse-conditional-effect%20%F0%9F%91%8D\n[twitter-badge]:\n  https://img.shields.io/twitter/url/https/github.com/alexkrolick/use-conditional-effect.svg?style=social\n[emojis]: https://github.com/alexkrolick/all-contributors#emoji-key\n[all-contributors]: https://github.com/alexkrolick/all-contributors\n[contributors]:\n  https://github.com/alexkrolick/use-conditional-effect/blob/master/CONTRIBUTORS.md\n[useeffect]: https://reactjs.org/docs/hooks-reference.html#useeffect\n[exhaustive-deps-lint]:\n  https://github.com/facebook/react/issues/14920#issuecomment-471070149\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexkrolick%2Fuse-conditional-effect","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexkrolick%2Fuse-conditional-effect","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexkrolick%2Fuse-conditional-effect/lists"}