@curi/react

About#

The @curi/react provides a number of React components that you can use for rendering your application.

Installation#

npm install @curi/react
yarn add @curi/react

Prefer inline scripts?

API#

<CuriProvider>#

import { CuriProvider } from '@curi/react';

The <CuriProvider> is the root Curi component for an application. It has two jobs:

  1. Re-rendering the application when a new response is emitted.
  2. Placing values on the context so that the other Curi components can access them.
Note: All of the other components provided by @curi/react must be descendants of a <CuriProvider>.

This component will listen for new responses to be emitted by your router and will automatically re-render your application when this happens.

const App = () => (
  <CuriProvider router={router}>
    {({ response, navigation, router }) => {
      const { body:Body } = response;
      return <Body response={response} />;
    }}
  </CuriProvider>
);

Props#

router#

A Curi router.

children#

children is a render-invoked prop that will be passed an object with three properties:

  1. response is the response object generated for the current location.
  2. navigation is additional information about the last navigation that doesn't make sense to place in the response.
  3. router is the Curi router.

<Curious>#

import { Curious } from '@curi/react';

A context consumer component for injecting router values into components.

class MyComponent extends React.Component {
  render() {
    return (
      <Curious>
        {({ router, response, navigation }) => {
          // pass these props to any components that need them
          return (
            <ThingThatNeedsResponse response={response} />
          );
        }}
      </Curious>
    )
  }
}

export default MyComponent;

Props#

children#

A render-invoked function that returns a React element. This function will receive an object with router, response and navigation properties.

<Active>#

import { Active } from '@curi/react';

The <Active> component allows you to render based on whether or not a route is "active" (its name and params match the current response's name and params) using a render-invoked children prop.

Note:

This relies on the active route interaction from @curi/route-active being added to your router.

import active from '@curi/route-active';

const router = curi(history, routes, {
  route: [active()]
});

Props#

name#

The name of the route to compare against the response object.

params#

An object containing route parameters. These will be compared against the route params of the response object.

children#

A render-invoked function whose first argument is whether the route (determined using the name and params) is active.

// response = { name: "Photo", params: { id: "abcde" }}

<Active name="Photo" params={{ id: "abcde" }}>
  {active => {
    // active === true
    return <Photo className={active ? "active" : "inactive"} />
  }}
</Active>
// <Photo className="active" />

<Active name="Photo" params={{ id: "qwerty" }}>
  {active => {
    // active === false
    return <Photo className={active ? "active" : "inactive"} />
  }}
</Active>
// <Photo className="inactive" />

The second argument passed to the render-invoked function is the current response. <Active> only checks if the route is active (i.e. matches the current location's pathname). If you want to check if the query or hash, you should do this yourself inside of the render-invoked function. You can compare the query/hash against the response's location.

<Active name="Home">
  {(active, response) => {
    const activeHash = response.hash === "ahoy"
    // ...
  }}
</Active>

partial#

When true, partial allows ancestor routes to be "active". Defaults to false.

// response = { name: "Photo", params: { id: "abcde" }}
// where "Photo" is a child route of "Album"

<Active name="Album">
  {active => {
    // active === false
    return <Album className={active ? "active" : "inactive"} />
  }}
</Active>
// <Album className="inactive" />

<Active name="Album" partial={true}>
  {active => {
    // active === true
    return <Album className={active ? "active" : "inactive"} />
  }}
</Active>
// <Album className="active" />

<Block>#

import { Block } from '@curi/react';

The <Block> component lets you prevent navigation until a user has confirmed that they want to navigate. This can be useful when the user attempts to navigate away from a partially filled form. This will not prevent the user from navigating to another site, it only works for navigation within the application.

Props#

active#

A boolean, which is true by default. When it is true, the navigation block is active. When it is false, navigation will not be blocked.

// will block navigation
<Block active={true} confirm={confirm} />

// will not block navigation
<Block active={false} confirm={confirm} />

confirm#

The confirm prop is a function that will be called whenever there is navigation. The function will receive four arguments: location, action, success, and failure. The location and action values are the location object that is being navigated to and the type of navigation. The success and failure arguments are functions that you should call depending on whether or not you want to let the navigation happen. When the navigation should occur, the confirm function should call the success function. When the navigation should be cancelled, the failure function should be called.

<Block
  confirm={({ location, action }, success, failure) => {
    const response = window.confirm("Shall we?");
    if (response) {
      success();
    } else {
      failure();
    }
  }}
/>