@curi/react-native

Version:

GitHub Repo

NPM Package

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

npm install @curi/react-native

createRouterComponent

A higher-order component that returns a Router component.

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

let router = createRouter(browser, routes);
let Router = createRouterComponent(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.

Link

A Link is used for navigating within your application. By default, this will render a TouchableHighlight. When the rendered element is pressed, it will use the router to navigate.

With the Link, instead of providing a URI to navigate to, you specify the name of the route that you want to link to. Then, the pathname of the URI you want the component to link to will be automatically generated for you.

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

<Link name='User' params={{ id: 16 }}>
  <Text>User 16</Text>
</Link>
// <TouchableHighlight>
//   <Text>User 16</Text>
// </TouchableHighlight>

Props

name

The name of the route that the Link should navigate to when it is pressed.

To navigate within the same location, the name can be skipped. This is useful for linking to hashes within the current page.

// Home route is { name: "Home", path: "" }
<Link name="Home">Home</Link>

params

If the named route (or any of its parents) include path parameters, they must be provided using the params prop.

// User route is { name: 'User', path: '/user/:id' }
<Link name='User' params={{ id: 16 }}>User 16</Link>

hash, query & state

The query, hash, and state values for the location to navigate to.

<Link
  name="Products"
  params={{ type: "vacuums" }}
  hash="iroomba"
  query="volume=loud"
  state={{ owner: "Tom Haverford" }}
>
  DJ Roomba
</Link>

children

A valid React Node (e.g. a React element, a string, or null).

// a React node
<Link name="Home">
  <Text>Home</Text>
</Link>

anchor

A Link renders a TouchableHighlight element by default, but this can be changed using the anchor prop. This can be useful for using styled components.

<Link
  name="User"
  params={{ id: 16 }}
  anchor={TouchableOpacity}
>
<Text>User 16</Text>
</Link>
// <TouchableOpacity>
//   <Text>User 16</Text>
// </TouchableOpacity>

rest

Any additional props attached to the Link will be attached to the element rendered by the Link.

<Link
  name="Home"
  style={{ ... }}
>
  <Text>Home</Text>
</Link>
// <TouchableOpacity style={{...}}>
//   <Text>Home</Text>
// </TouchableOpacity>

AsyncLink

An AsyncLink is similar to a Link, but uses a render-invoked function as its children component.

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

<AsyncLink name='User' params={{ id: 16 }}>
  {navigating => {
    return navigating
      ? <Text>Navigating to User 16</Text>
      : <Text>Go to User 16</Text>
  }}
</AsyncLink>

<TouchableHighlight>
  <Text>Go to User 16</Text>
</TouchableHighlight>
// press button
<TouchableHighlight>
  <Text>Navigating to User 16</Text>
</TouchableHighlight>

Props

children

A render-invoked children function that is called with the AsyncLink's navigation state. The navigation state is false to start, true when the AsyncLink is clicked, and false when the the navigation finishes/is cancelled.

<AsyncLink name="User" params={{ id: 1 }}>
  {navigating => (
    <React.Fragment>
      <Text>User 1</Text>
      {navigating ? <Spinner /> : null}
    </React.Fragment>
  )}
</AsyncLink>

anchor

See Link anchor

rest

See Link rest

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() {
  let {
    response,
    navigation
  } = useResponse();
  return (
    <ThingThatNeedsResponse
      response={response}
    />
  );
}

useRouter

The useRouter hook returns the router object.

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

function App() {
  let 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
}) {
  let active = useActive({ name, params, partial });
  return (
    <Link
      name={name}
      params={params}
      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

useConfirm

The useConfirm hook adds and removes a navigation confirmation.

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

useConfirm(confirmation);
// confirmation will be called when the user navigates

useConfirm();
// confirmation will not be called when the user navigates

Arguments

fn

When passed a function, the function will be called when the user navigates and give them the option to confirm or prevent the navigation.

When called with no argument, the existing navigation confirmation will be removed.

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() {
  let cancel = useNavigating();

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

useURL

The useURL hook creates a URL string.

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

let 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>
    );
  }
}

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

class MyComponent {
  render() {
    return (
      <RouterConsumer>
        {router => {
          return (
            <button onClick={e => {
              login();
              let 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.