Skip to content

Latest commit

 

History

History
104 lines (77 loc) · 5.49 KB

README.md

File metadata and controls

104 lines (77 loc) · 5.49 KB

angularjs-react

A library for using React components as AngularJS directives. The main advantage over other similar libraries is that it supports angular content within react components.

Angular content can be placed inside a react container component as if the component were a regular Angular directive. Content will render and update as expected. Example:

<my-react-container>
  <span ng-if="showContent">{{controller.content}}</span>
</my-react-container>

See it live here

Installation

npm install angularjs-react --save

Or just download the umd bundle manually.

Usage

  1. Wrap your react component into an Angular directive using angularjs-react
import directify from 'angularjs-react/dist/angularjs-react';
// If including the library directly in a <script> tag, use `window.directify`
import { Button } from 'react-toolbox/lib/button';
angular.module('app', []).directive('reactButton', directify(Button));
  1. Use the directive in your Angular templates
<react-button>
  <span>{{model.text}}</span>
</react-button>

Passing Props

angularjs-react supports passing props to react components. Attributes that should be passed as props need to be prefixed with one of the prefixes described in the sections below. The reason for using prefixes instead of matching attribute names with component PropTypes is that, firstly, not all components have PropTypes defined and, secondly, there could easily be cases where other attributes (such as angular directives) happen to have the same name as one of the component props but shouldn't be passed as input props.
The two main types of props are input props and callback props.

Input Props
Input props need to be prefixed with re-in- so if the react component expects an input prop named rowHeight then this should be passed as re-in-row-height="model.rowHeight".

The attribute value is interpreted as an angular expression and will be used to setup a (deep) watch on the current scope.

NOTE: if the value of the prop is intended to be a string literal, it needs to be surrounded by quotes, i.e. re-in-row-height="'20'"

By default a deep watch will be used to observe changes in an input prop. If the input prop can be treated as immutable and only a shallow watch is required, then use the prefix re-iin- (for immutable input).

Callback props
Callback props need to be prefixed with re-cb- and the attribute is also treated as an angular expression. However in the case of callbacks props, the expression is only evaluated when the callback is called. The arguments that are passed to the callback function are available as args which is an array of all the arguments that the callback was called with. arg can also be used to reference the first argument.

Example:

<react-input re-in-value="model.value"
    re-cb-on-change="model.value = arg">  
</react-input>

Special Props

  • re-ref

This is equivalent to the ref prop in React and is used for getting a reference to the component once it has rendered. Again, the value of this attribute is treated as an angular expression which is evaluated when React calls the ref callback for the component. The reference is available as ref in the expression.
Example:
<react-component re-ref="model.reactRef = ref"></react-component>

Getting a reference to the react component can sometimes be useful. For example, if a SidePanel component had an open method then the angular app could get a reference to the component and call .open() on it to open the side panel.

  • re-react

This changes the way the child elements are handled.

By default, child elements are removed and compiled separately using angular. A "dummy" child component is passed to react instead which is then replaced with the real angular content after rendering.
This works in most cases except when the react component tries to perform processing on its children. In this case re-react can be used to tell angularjs-react to convert the immediate child elements to react components and only treat the contents of those as angular content. So essentially the angular transclusion only happens one level deeper. The children elements can also have re-in- attributes which will be used as props when converting them to react elements.

Example:

<react-grid-layout re-react>
  <!-- Each div generated by ng-repeat will be converted to a react element and passed as children to the react-grid-layout component -->
  <div ng-repeat="block in layout" re-in-key="block.i">
    <div>{{block.content}}</div>
  </div>
</react-grid-layout>
  • re-replace

This is used to have the React component actually replace the directive wrapper element. This should be avoided and is generally only used for inner components. Unfortunately some component libraries use css selectors that rely on exact element hierarchies so leaving the directive wrapper element in place breaks the styling.

Example:

<react-toolbox-button>
  <github-icon re-replace></github-icon> {{text}}
</react-toolbox-button>

Demo App

In the demo directory is a basic angular app that showcases several different react components from public component libraries.

The demo is live here