Adapters: React

Intro

react-winjs is a library which exposes each WinJS control as a React component.

API Differences from WinJS

  1. Instantiating a winJS control
  2. In WinJS, an element is declared through using the declarative markup:

    <div data-win-control="WinJS.UI.FlipView"></div>

    In the react-winjs adapter, an element would be declared like this

    <ReactWinJS.FlipView itemDataSource={this.props.ratingsList.dataSource} itemTemplate={this.flipViewItemRenderer} onPageSelected={this.handlePageSelected} >
  3. Accessing the winControl
  4. Like WinJS, the winControl attribute returns the WinJS control instance for a component. For example, winControl on a react-winjs ListView component will return an instance of WinJS.UI.ListView.

  5. Properties
  6. Properties of react-winjs React components mostly match the properties of the WinJS controls. React components have a few additional props, applied to the WinJS control root element:

    • className: the element's CSS className.
    • style: this object's keys are camelCased CSS attributes, its values are their values. Similar to React's style prop, the values have types:
      • string: normal strings
      • number: Generally converted to a string with "px" appended. Unitless CSS properties (e.g. opacity, flexGrow) are left alone.
      • falsy: Falsy values except 0 become empty strings.
    • id: A string with the element's id.
    • aria-controls, aria-expanded: A string with the value of the aria attribute.

    WinJS controls themselves typically manipulate their root elements, in addition to how you may manipulate them from React. For example, the ListView will add classes such as win-listview and win-disposable to its root element. react-winjs implements the style and className props to avoid conflicting with WinJS additions.

  7. Events
  8. Events are exposed as camelCased props with the prefix 'on'. For example, WinJS's onbeforeshow event is exposed as the onBeforeShow prop.

  9. Special Props
  10. Some react-winjs components have additional props. For example, the react-winjs SplitView has a paneComponent prop which enables you to specify the pane's content as a React component. Such special props are noted under the documentation on GitHub for the particular control.

  11. Utility Functions
  12. reactRenderer(componentFunction): Enables an itemTemplate to be specified as a React component. Given a function that returns a React component, returns an item renderer function that can be used with WinJS controls. See the FlipView and ListView examples on GitHub.

    Learn More

    Further information at GitHub: react-winjs project.