@curi/react-native

GitHub logoGitHub RepoNPM logoNPM Package

Installation

npm install @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.

API

curiProvider

The application needs a component at its root to re-render the application when new responses are emitted and to make routing related available through React's context. This component is created by passing the Curi router to the curiProvider function.

Note:

Why does @curi/react-native export a function to create a component and not just a component? Props signify values that can change, but an application should only ever have one router. By hard-coding the router into a component, we avoid having to handle the possibility of switching routers (which should not happen).

Note:

All of the other components provided by @curi/react-native must be descendants of the component created by curiProvider.

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

const router = curi(history, routes);
const Router = curiProvider(router);

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

Arguments

router

A Curi router.

import { curiProvider } from "@curi/react-native";

const router = curi(history, routes);
const Router = curiProvider(router);

Props

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-native';

function ActiveLink({
  name,
  params,
  partial,
  forward,
  ...rest
}) {
  return (
    <Active name={name} params={params} partial={partial}>
      {active => (
        <Link
          name={name}
          params={params}
          {...rest}
          forward={{
            ...forward,
            style: [...forward.style, activeStyle]
          }}
        />
      )}
    </Active>
  );
}

<ActiveLink name="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();
    }
  }}
/>