@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

createRouterComponent

A higher-order component that returns a Router component.

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

const router = createRouter(browser, routes);
const Router = createRouterComponent(router);
Note:

Why a higher-order component not regular component? Props signify values that can change, but an application should only ever have one router. Using a higher-order component hard-codes the provided router as the one and only router.

Return Value

A component that sets routing context data. Any component that relies on routing data must be a descendant of the Router.

children

The Router takes any valid React node (elements, strings, etc.) as its children.

useResponse

The useResponse hook reads the current response and navigation values from React's context. This will be called every time a new response is emitted.

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

function App() {
  const {
    response,
    navigation
  } = useResponse();
  return (
    <ThingThatNeedsResponse
      response={response}
    />
  );
}

useRouter

The useRouter hook returns the router object.

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

function App() {
  const router = useRouter();
  // ...
}

useActive

The useActive hook determines if a route is active by comparing a route name (and possibly params) to a response object.

import { useActive, Link } from '@curi/react-native';

function ActiveLink({
  name,
  params,
  partial,
  children
}) {
  const active = useActive({ name, params, partial });
  return (
    <Link
      name={name}
      params={params}
      forward={{ className: active ? "active" : "" }}
    >
      {children}
    </Link>
  );
}

<ActiveLink name="Home">Home</ActiveLink>

Options

useActive takes a single argument, an options object.

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.

partial

Allows ancestor routes to be considered active when true. Defaults to false.

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

useActive({ name: "User" }); // false
useActive({ name: "User", partial: true }); // true

components

The base active check only checks that the route (i.e. pathname) is active. components allows you to check if other components of the location are also active.

useActive({
  name: "Results",
  components: loc => loc.query === "page=3"
});

// active for /results?page=3
// not active for /results?page=1

useNavigating

The useNavigating hook is used to determine if the application is currently navigating. It pairs up with router.cancel to enable cancelling asynchronous navigation.

This is only useful for asynchronous routes because with synchronous routes, navigation happens immediately.

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

function CancelNavigation() {
  const cancel = useNavigating();

  return cancel
    ? <button onClick={cancel}>Cancel</button>
    : null;
}
Note:

Ideally, browsers would natively handle asynchronous navigation and this would be unnecessary. For the time being, this is the next best solution.

useURL

The useURL hook creates a URL string.

import { useURL } from '@curi/react-dom';

const href = useURL({
  name: "Video",
  params: { id: "jaifeo9" } },
  hash: "comments",
  query: "t=15"
});
// href = "/video/jaifeo9?t=15#comments"

Options

name

The name of the route to generate the location's pathname from. If this is not provided, the generated location's pathname will be an empty string ("");

params

An object of params for the named route.

hash

A hash string for the location.

query

The location's query value.

By default, this is expected to be a string, but if you configure your history object with the query option, this may be something else.

<ResponseConsumer>

A context consumer component for injecting response values into components. Its primary use case is in class components.

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

class MyComponent {
  render() {
    return (
      <ResponseConsumer>
        {({ response, navigation }) => {
          // pass these props to any components
          // that needs them
          return (
            <ThingThatNeedsResponse
              response={response}
            />
          );
        }}
      </ResponseConsumer>
    );
  }
}

Props

children

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

<RouterConsumer>

A context consumer component for injecting the router into components. Its primary use case is in class components.

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

class MyComponent {
  render() {
    return (
      <RouterConsumer>
        {router => {
          return (
            <button onClick={e => {
              login();
              const url = router.url({ name: "Home" });
              router.navigate({ url });
            }}>
              Submit
            </button>
          );
        }}
      </RouterConsumer>
    );
  }
}

Props

children

A render-invoked function that returns a React element. This function will receive the application's router.