Documentation

Intro

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

API Differences from WinJS

For the most part, the props of the react-winjs React components match the properties of the WinJS controls. The React components have one additional prop:

• className: Manipulates the className of the root element of the WinJS control. What's interesting about a control's root element is that, not only might you want to manipulate it from React, but WinJS controls themselves typically manipulate their root elements. For example, the ListView will add classes such as win-listview and win-disposable to its root element. The className prop enables you to contribute to the root element's class names without stomping on the ones that WinJS added.

Each component provides a property called winControl which returns the instance of the WinJS control. For example, winControl on a react-winjs ListView component will return an instance of WinJS.UI.ListView.

Events are exposed as camel cased props that begin with on. For example, WinJS's onbeforeshow event is exposed as the onBeforeShow prop.

Utility Functions

• 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.

Controls: Example Usages

AppBar and AppBarCommand

<ReactWinJS.AppBar>
    <ReactWinJS.AppBarCommand key="home" icon="home" label="Home" />
    <ReactWinJS.AppBarCommand key="save" icon="save" label="Save" />
</ReactWinJS.AppBar>

Limitations:

• Each AppBarCommand must have a key.
• The AppBarCommand's ref prop does not work.
• AppBarCommand.type is initialize only. Once you set it, you cannot change it without creating a new component with a new key.
• AppBarCommand.flyout doesn't work.

AutoSuggestBox

<ReactWinJS.AutoSuggestBox placeholderText="Type a city" />

BackButton

<ReactWinJS.BackButton />

Command

See ToolBar

ContentDialog

<ReactWinJS.ContentDialog
  ref="dialog"
  title="Urgent Message"
  primaryCommandText="OK"
  secondaryCommandText="Cancel"
/>
  <div>
    This content will appear in the body of the ContentDialog. You can put <i>arbitrary</i> HTML in here.
  </div>
</ReactWinJS.ContentDialog>

// ...

// In an event handler:
this.refs.dialog.winControl.show().then(function (eventObject) {
  // eventObject.result tells you what caused the dialog to get dismissed.
});

DatePicker

<ReactWinJS.DatePicker current={this.state.date} onChange={this.handleDateChange} />

FlipView

<ReactWinJS.FlipView
  itemDataSource={this.props.ratingsList.dataSource}
  itemTemplate={this.flipViewItemRenderer}
  onPageSelected={this.handlePageSelected} />

// ...

// itemDataSource
ratingsList: new WinJS.Binding.List([{ rating: 4 }, { rating: 2 }])

// itemTemplate
flipViewItemRenderer: ReactWinJS.reactRenderer(function (item) {
  return <div>This flip view item's rating is: {item.data.rating}</div>;
})

Flyout

<ReactWinJS.Flyout ref="flyout">
  <div>This is the flyout content!!</div>
</ReactWinJS.Flyout>

// ...

// In an event handler:
this.refs.flyout.show(anchorElement);

Hub and HubSection

<ReactWinJS.Hub>
    <ReactWinJS.HubSection key="sectionA" header="First section" isHeaderStatic={true}>
      <div>Hubs are useful for varied content</div>
    </ReactWinJS.HubSection>
    <ReactWinJS.HubSection key="sectionB" header="The second section">
      <div>This hub is boring however, it only contains one piece of dynamic content: {ratings.length}</div>
    </ReactWinJS.HubSection>
    <ReactWinJS.HubSection key="sectionC" header="The tail...">
      <div>Because it's only purpose is to show how to create a hub</div>
    </ReactWinJS.HubSection>
</ReactWinJS.Hub>

Limitations:

• Each HubSection must have a key.
• The HubSection's ref prop does not work.

ItemContainer

<ReactWinJS.ItemContainer>
  <div>
    An ItemContainer is a wrapper around content that adds
    pressed and selection behaviors!
  </div>
</ReactWinJS.ItemContainer>

ListView

<ReactWinJS.ListView
  itemDataSource={this.props.ratingsList.dataSource}
  itemTemplate={listViewItemRenderer}
  layout={listViewLayout} />
</ReactWinJS.ListView>

// ...

// itemDataSource
ratingsList: new WinJS.Binding.List([{ rating: 4 }, { rating: 2 }])

// itemTemplate
listViewItemRenderer: ReactWinJS.reactRenderer(function (item) {
  return <div>This list view item's rating is: {item.data.rating}</div>;
})

// layout
listViewLayout: new WinJS.UI.ListLayout();

Menu and MenuCommand

<ReactWinJS.Menu ref="menu">
    <ReactWinJS.MenuCommand key="commandA" label="command the first" />
    <ReactWinJS.MenuCommand key="commandB" label="command the second" />
</ReactWinJS.Menu>

// ...

// In an event handler:
this.refs.menu.winControl.show(anchorElement);

Limitations:

• Each MenuCommand must have a key.
• The MenuCommand's ref prop does not work.
• MenuCommand.type is initialize only. Once you set it, you cannot change it without creating a new component with a new key.
• MenuCommand.flyout doesn't work.

NavBar and friends

<ReactWinJS.NavBar>
    <ReactWinJS.NavBarContainer>
        <ReactWinJS.NavBarCommand key="home" label="Home" icon="home" tooltip="Go home!!" />
        <ReactWinJS.NavBarCommand key="save" label="Save" icon="save" />
    </ReactWinJS.NavBarContainer>
</ReactWinJS.NavBar>

Limitations:

• Each NavBarCommand must have a key.
• The NavBarCommand's ref prop does not work.

Pivot and PivotItem

<ReactWinJS.Pivot>
    <ReactWinJS.PivotItem key="itemA" header="First">
      <div>Pivots are useful for varied content</div>
    </ReactWinJS.PivotItem>
    <ReactWinJS.PivotItem key="itemB" header="Second">
      <div>This Pivot is boring however, it only contains one piece of dynamic content: {ratings.length}</div>
    </ReactWinJS.PivotItem>
    <ReactWinJS.PivotItem key="itemC" header="Tail...">
      <div>Because it's only purpose is to show how to create a Pivot</div>
    </ReactWinJS.PivotItem>
</ReactWinJS.Pivot>

Limitations:

• Each PivotItem must have a key.
• The PivotItem's ref prop does not work.

Rating

<ReactWinJS.Rating maxRating={5} userRating={this.state.rating} />

SearchBox

<ReactWinJS.SearchBox placeholderText="Search" />

SemanticZoom

Not yet supported

SplitView

<ReactWinJS.SplitView
  paneComponent={<div>SplitView Navigation Pane</div>}
  contentComponent={<div>SplitView Content Area</div>} />

TimePicker

<ReactWinJS.TimePicker current={this.state.time} />

ToggleSwitch

<ReactWinJS.ToggleSwitch
  checked={this.props.toggleOn}
  onChange={this.handleToggle}
  labelOn="Switch is On"
  labeOff="Switch is Off" />

ToolBar

<ReactWinJS.ToolBar>
    <ReactWinJS.Command key="add" label="This is a ToolBar command" icon="add" />
    <ReactWinJS.Command key="remove" label="Another ToolBar command" icon="remove" />
</ReactWinJS.ToolBar>

Limitations:

• Each Command must have a key.
• The Command's ref prop does not work.
• Command.type is initialize only. Once you set it, you cannot change it without creating a new component with a new key.
• Command.flyout doesn't work.

Tooltip

<ReactWinJS.Tooltip
  contentComponent={<div>This can have arbitrary content, like images...</div>}>
  <div>This has a tooltip, hover and see...</div>
</ReactWinJS.Tooltip>