{"id":13403921,"url":"https://github.com/ngReact/ngReact","last_synced_at":"2025-03-14T08:32:17.461Z","repository":{"id":12572203,"uuid":"15242752","full_name":"ngReact/ngReact","owner":"ngReact","description":"Use React Components in Angular","archived":true,"fork":false,"pushed_at":"2019-02-15T12:51:36.000Z","size":1269,"stargazers_count":2605,"open_issues_count":0,"forks_count":260,"subscribers_count":83,"default_branch":"master","last_synced_at":"2024-10-30T00:09:17.749Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://ngReact.github.io/ngReact","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/ngReact.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-12-17T02:09:22.000Z","updated_at":"2024-10-29T10:45:09.000Z","dependencies_parsed_at":"2022-09-05T08:41:33.396Z","dependency_job_id":null,"html_url":"https://github.com/ngReact/ngReact","commit_stats":null,"previous_names":["davidchang/ngreact"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngReact%2FngReact","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngReact%2FngReact/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngReact%2FngReact/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngReact%2FngReact/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ngReact","download_url":"https://codeload.github.com/ngReact/ngReact/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243532532,"owners_count":20306153,"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-30T19:01:36.371Z","updated_at":"2025-03-14T08:32:17.169Z","avatar_url":"https://github.com/ngReact.png","language":"JavaScript","readme":"[![Build Status](https://travis-ci.org/ngReact/ngReact.svg?branch=master)](https://travis-ci.org/ngReact/ngReact) [![Pair on this](https://tf-assets-staging.s3.amazonaws.com/badges/thinkful_repo_badge.svg)](http://start.thinkful.com/react/?utm_source=github\u0026utm_medium=badge\u0026utm_campaign=ngReact)\n\n\u003e **Note: For a more modern alternative to ngReact, we recommend [react2angular](https://github.com/coatue/react2angular), [angular2react](https://github.com/coatue/angular2react), and [ngimport](https://github.com/bcherny/ngimport).**\n\n# ngReact\n\nThe [React.js](http://facebook.github.io/react/) library can be used as a view component in web applications. ngReact is an Angular module that allows React Components to be used in [AngularJS](https://angularjs.org/) applications.\n\nMotivation for this could be any of the following:\n\n- You need greater performance than Angular can offer (two way data binding, Object.observe, too many scope watchers on the page) and React is typically more performant due to the Virtual DOM and other optimizations it can make\n\n- React offers an easier way to think about the state of your UI; instead of data flowing both ways between controller and view as in two way data binding, React typically eschews this for a more unidirectional/reactive paradigm\n\n- Someone in the React community released a component that you would like to try out\n\n- You're already deep into an Angular application and can't move away, but would like to experiment with React\n\n# Installation\n\nInstall via Bower:\n\n```bash\nbower install ngReact\n```\n\nor via npm:\n\n```bash\nnpm install ngreact\n```\n\n# Usage\n\nThen, just make sure Angular, React, and ngReact are on the page,\n\n```html\n\u003cscript src=\"bower_components/angular/angular.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"bower_components/react/react.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"bower_components/react/react-dom.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"bower_components/ngReact/ngReact.min.js\"\u003e\u003c/script\u003e\n```\n\nand include the 'react' Angular module as a dependency for your new app\n\n```html\n\u003cscript\u003e\n    angular.module('app', ['react']);\n\u003c/script\u003e\n```\n\nand you're good to go.\n\n# Features\n\nSpecifically, ngReact is composed of:\n\n- `react-component`, an Angular directive that delegates off to a React Component\n- `reactDirective`, a service for converting React components into the `react-component` Angular directive\n\n**ngReact** can be used in existing angular applications, to replace entire or partial views with react components.\n\n## The react-component directive\n\nThe `react-component` directive is a generic wrapper for embedding your React components.\n\nWith an Angular app and controller declaration like this:\n\n```javascript\nangular\n  .module('app', ['react'])\n  .controller('helloController', function($scope) {\n    $scope.person = { fname: 'Clark', lname: 'Kent' };\n  });\n```\n\nAnd a React Component like this\n\n```javascript\nvar HelloComponent = React.createClass({\n  propTypes: {\n    fname: React.PropTypes.string.isRequired,\n    lname: React.PropTypes.string.isRequired\n  },\n  render: function() {\n    return (\n      \u003cspan\u003e\n        Hello {this.props.fname} {this.props.lname}\n      \u003c/span\u003e\n    );\n  }\n});\napp.value('HelloComponent', HelloComponent);\n```\n\nThe component can be used in an Angular view using the react-component directive like so:\n\n```html\n\u003cbody ng-app=\"app\"\u003e\n  \u003cdiv ng-controller=\"helloController\"\u003e\n    \u003creact-component name=\"HelloComponent\" props=\"person\" watch-depth=\"reference\"/\u003e\n  \u003c/div\u003e\n\u003c/body\u003e\n```\n\nHere:\n\n- `name` attribute checks for an Angular injectable of that name and falls back to a globally exposed variable of the same name\n- `props` attribute indicates what scope properties should be exposed to the React component\n- `watch-depth` attribute indicates what watch strategy to use to detect changes on scope properties. The possible values for react-component are `reference`, `collection` and `value` (default)\n\n## The reactDirective service\n\nThe reactDirective factory, in contrast to the reactComponent directive, is meant to create specific directives corresponding to React components. In the background, this actually creates and sets up directives specifically bound to the specified React component.\n\nIf, for example, you wanted to use the same React component in multiple places, you'd have to specify `\u003creact-component name=\"yourComponent\" props=\"props\"\u003e\u003c/react-component\u003e` repeatedly, but if you used reactDirective factory, you could create a `\u003cyour-component\u003e\u003c/your-component\u003e` directive and simply use that everywhere.\n\nThe service takes the React component as the argument.\n\n```javascript\napp.directive('helloComponent', function(reactDirective) {\n  return reactDirective(HelloComponent);\n});\n```\n\nAlternatively you can provide the name of the component\n\n```javascript\napp.directive('helloComponent', function(reactDirective) {\n  return reactDirective('HelloComponent');\n});\n```\n\nThis creates a directive that can be used like this:\n\n```html\n\u003cbody ng-app=\"app\"\u003e\n  \u003cdiv ng-controller=\"helloController\"\u003e\n    \u003chello-component fname=\"person.fname\" lname=\"person.lname\" watch-depth=\"reference\"\u003e\u003c/hello-component\u003e\n  \u003c/div\u003e\n\u003c/body\u003e\n```\n\nThe `reactDirective` service will read the React component `propTypes` and watch attributes with these names. If your react component doesn't have `propTypes` defined you can pass in an array of attribute names to watch. If you don't pass any array of attribute names, fall back to use directive attributes as a last resort. By default, attributes will be watched by value however you can also choose to watch by reference or collection by supplying the watch-depth attribute. Possible values are `reference`, `collection` and `value` (default).\n\n```javascript\napp.directive('hello', function(reactDirective) {\n  return reactDirective(HelloComponent, ['fname', 'lname']);\n});\n```\n\nYou may also customize the watch depth per prop/attribute by wrapping the name and an options object in an array inside the props array:\n\n```javascript\napp.directive('hello', function(reactDirective) {\n  return reactDirective(HelloComponent, [\n    'person', // takes on the watch-depth of the entire directive\n    ['place', { watchDepth: 'reference' }],\n    ['things', { watchDepth: 'collection' }],\n    ['ideas', { watchDepth: 'value' }]\n  ]);\n});\n```\n\nBy default, ngReact will wrap any functions you pass as in `scope.$apply`. You may want to override this behavior, for instance, if you are passing a React component as a prop. You can achieve this by explicitly adding a `wrapApply: false` in the prop config:\n\n```javascript\napp.directive('hello', function(reactDirective) {\n  return reactDirective(HelloComponent, [\n    'person',\n    ['place', { watchDepth: 'reference' }],\n    ['func', { watchDepth: 'reference', wrapApply: false }]\n  ]);\n});\n```\n\nIf you want to change the configuration of the directive created the `reactDirective` service, e.g. change `restrict: 'E'` to `restrict: 'C'`, you can do so by passing in an object literal with the desired configuration.\n\n```javascript\napp.directive('hello', function(reactDirective) {\n  return reactDirective(HelloComponent, undefined, { restrict: 'C' });\n});\n```\n\n### Minification\n\nA lot of automatic annotation libraries including ng-annotate skip implicit annotations of directives. Because of that you might get the following error when using directive in minified code:\n\n```\nUnknown provider: eProvider \u003c- e \u003c- helloDirective\n```\n\nTo fix it add explicit annotation of dependency\n\n```javascript\nvar helloDirective = function(reactDirective) {\n  return reactDirective('HelloComponent');\n};\nhelloDirective.$inject = ['reactDirective'];\napp.directive('hello', helloDirective);\n```\n\n## Reusing Angular Injectables\n\nIn an existing Angular application, you'll often have existing services or filters that you wish to access from your React component. These can be retrieved using Angular's dependency injection. The React component will still be render-able as aforementioned, using the react-component directive.\n\nIt's also possible to pass Angular injectables and other variables as fourth parameter straight to the reactDirective, which will then attach them to the props\n\n```javascript\napp.directive('helloComponent', function(reactDirective, $ngRedux) {\n  return reactDirective(HelloComponent, undefined, {}, { store: $ngRedux });\n});\n```\n\nBe aware that you can not inject Angular directives into JSX.\n\n```javascript\napp.filter('hero', function() {\n  return function(person) {\n    if (person.fname === 'Clark' \u0026\u0026 person.lname === 'Kent') {\n      return 'Superman';\n    }\n    return person.fname + ' ' + person.lname;\n  };\n});\n\n/** @jsx React.DOM */\napp.factory('HelloComponent', function($filter) {\n  return React.createClass({\n    propTypes: {\n      person: React.PropTypes.object.isRequired\n    },\n    render: function() {\n      return \u003cspan\u003eHello $filter('hero')(this.props.person)\u003c/span\u003e;\n    }\n  });\n});\n```\n\n```html\n\u003cbody ng-app=\"app\"\u003e\n  \u003cdiv ng-controller=\"helloController\"\u003e\n    \u003creact-component name=\"HelloComponent\" props=\"person\" /\u003e\n  \u003c/div\u003e\n\u003c/body\u003e\n```\n\n## Jsx Transformation in the browser\n\nDuring testing you may want to run the `JSXTransformer` in the browser. For this to work with angular you need to make sure that the jsx code has been transformed before the angular application is bootstrapped. To do so you can [manually bootstrap](https://docs.angularjs.org/guide/bootstrap#manual-initialization) the angular application. For a working example see the [jsx-transformer example](https://github.com/davidchang/ngReact/tree/master/examples/jsx-transformer).\n\nNOTE: The workaround for this is hacky as the angular bootstap is postponed in with a `setTimeout`, so consider [transforming jsx in a build step](http://facebook.github.io/react/docs/getting-started.html#offline-transform).\n\n## Usage with [webpack](https://webpack.github.io/) and AngularJS \u003c 1.3.14\n\nCommonJS support was [added to AngularJS in version 1.3.14](https://github.com/angular/angular.js/blob/master/CHANGELOG.md#1314-instantaneous-browserification-2015-02-24). If you use webpack and need to support AngularJS \u003c 1.3.14, you should use webpack's [exports-loader](https://github.com/webpack/exports-loader) so that `require('angular')` returns the correct value. Your webpack configuration should include the following loader config:\n\n```js\n...\nmodule: {\n  loaders: [\n    {\n      test: path.resolve(__dirname, 'node_modules/angular/angular.js'),\n      loader: 'exports?window.angular'\n    }\n  ]\n},\n...\n```\n\n## Developing\n\nBefore starting development run\n\n```bash\nnpm install\nbower install\n```\n\nBuild minified version and run tests with\n\n```bash\ngrunt\n```\n\nContinually run test during development with\n\n```bash\ngrunt karma:background watch\n```\n\n### Running the examples\n\nThe examples in the `examples/` folder use `bower_components`. To install these first install bower on your machine\n\n```\nnpm install --global bower\n```\n\nThen install the bower components\n\n```\nbower install\n```\n\nThe examples need to be run on a local webserver like https://www.npmjs.com/package/http-server.\n\nRun the examples by starting a webserver in the project root folder.\n\n# Community\n\n## Maintainers\n\n- Kasper Bøgebjerg Pedersen (@kasperp)\n- David Chang (@davidchang)\n\n## Contributors\n\n- Matthieu Prat (matthieuprat)\n- @Shuki-L\n- Fabien Rassinier (@frassinier)\n- Guilherme Hermeto (@ghermeto)\n- @thorsten\n- @katgeorgeek\n- @rosston\n- Tihomir Kit (@pootzko)\n- Alexander Beletsky (@alexanderbeletsky)\n- @matthieu-ravey\n- @ethul\n- Devin Jett (@djett41)\n- Marek Kalnik (@marekkalnik)\n- @oriweingart\n- Basarat Ali Syed (@basarat)\n- Rene Bischoff (@Fjandin)\n- Zach Pratt (@zpratt)\n- Alex Abenoja (@aabenoja)\n- @villesau\n- @bdwain\n- @onumossn\n","funding_links":[],"categories":["JavaScript","Directive"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FngReact%2FngReact","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FngReact%2FngReact","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FngReact%2FngReact/lists"}