@curi/react-native

About#

The @curi/react-native package provides components to use Curi routing in a React Native application.

For more information on using Curi with React Native, please check out the React Native guide.

Installation#

If you have Node and NPM installed, you can install the package through npm (or yarn if you prefer).

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

API#

<CuriProvider>#

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-native must be descendants of a <CuriProvider>.

<CuriProvider> will observe your router so that it can automatically re-render your application after navigation.

import { CuriProvider } from '@curi/react-native';
          
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 function. When it is called, it will be passed an object with three properties:

propertydescription
responsethe response object generated for the current location
navigationthe action of the navigation and the previous response object
routerthe Curi router

<Curious>#

A context consumer component for injecting router values into components.

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

const  MyComponent = () => (
  <Curious>
    {({ router, response, navigation }) => {
      // pass these props to any components that need them
      return (
        <ThingThatNeedsResponse response={response} />
      );
    }}
  </Curious>
);

Props#

children#

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

<Active>#

The <Active> component is used 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 function.

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

const ActiveLink = ({ to, params, partial, ...rest}) => (
  <Active name={to} params={params} partial={partial}>
    {active => (
      <Link
        to={to}
        params={params}
        {...rest}
        className={active ? "active" : ""}
      />
    )}
  </Active>
);

<ActiveLink to="Home">Home</ActiveLink>
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 => ( // if active === true
    <Photo className={active ? "active" : "inactive"} />
  )}
</Active>
// <Photo className="active" />

<Active name="Photo" params={{ id: "qwerty" }}>
  {active => ( // if active === false
    <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 considered active. Defaults to false.

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

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

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

<Block>#

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.

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

Props#

active#

A boolean, which is true by default. When it is true, the navigation will be blocked. 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.

argumentdescription
locationthe location that is being navigated to
actionthe type of navigation
successa function to call when navigation should happen
failurea function to call when navigation should be cancelled.
<Block
  confirm={({ location, action }, success, failure) => {
    const response = window.confirm("Shall we?");
    if (response) {
      success();
    } else {
      failure();
    }
  }}
/>