React `use` API

Modern react comes with a utility function called use that has a number of features. A core feature is that it can be used as a replacement for useContext and as we discuss below, use offers more flexibility.

Example with `useContext`

Here is a simple example where we call useContext to resolve the value of a context.

Button.tsx

ThemeContext.tsx

App.tsx

const baseStyle = {
  borderRadius: "5px",
  transition: "all .2s",
};
const lightStyle = {
  ...baseStyle,
  background: "#fff",
  color: "#000",
};
const darkStyle = {
  ...baseStyle,
  background: "#000",
  color: "#fff",
};

import { ThemeContext } from "./ThemeContext";
import { useContext } from "react";

export type ButtonProps = {
  onClick: () => void;
  children: React.ReactNode;
};

export const Button = (props: ButtonProps) => {
  const theme = useContext(ThemeContext);
  const style = theme == "light" ? lightStyle : darkStyle;

  return (
    <button style={style} onClick={props.onClick}>
      {props.children}
    </button>
  );
};

Example with `use`

At its core use is a drop in replacement for useContext. So we can simply replace our call to useContext and get the same functionality. This is demonstrated below.

Button.tsx

ThemeContext.tsx

App.tsx

const baseStyle = {
  borderRadius: "5px",
  transition: "all .2s",
};
const lightStyle = {
  ...baseStyle,
  background: "#fff",
  color: "#000",
};
const darkStyle = {
  ...baseStyle,
  background: "#000",
  color: "#fff",
};

import { ThemeContext } from "./ThemeContext";
import { use } from "react";

export type ButtonProps = {
  onClick: () => void;
  children: React.ReactNode;
};

export const Button = (props: ButtonProps) => {
  const theme = use(ThemeContext);
  const style = theme == "light" ? lightStyle : darkStyle;

  return (
    <button style={style} onClick={props.onClick}>
      {props.children}
    </button>
  );
};

Limitation of `useContext`

useContext must follow the rules of hooks and therefore it cannot be called conditionally or in loops.

As an example demonstrated below, even though we do not need the value from the context if custom styling is enabled, we still must make a called to useContext as we cannot call it conditionally.

Button.tsx

ThemeContext.tsx

App.tsx

const baseStyle = {
  borderRadius: "5px",
  transition: "all .2s",
};
const lightStyle = {
  ...baseStyle,
  background: "#fff",
  color: "#000",
};
const darkStyle = {
  ...baseStyle,
  background: "#000",
  color: "#fff",
};
const customStyle = {
  ...baseStyle,
  background:
    "linear-gradient(to right, red, orange, yellow, green, blue, indigo, violet)",
  color: "#fff",
};

import { ThemeContext } from "./ThemeContext";
import { useContext } from "react";

export type ButtonProps = {
  onClick: () => void;
  children: React.ReactNode;
  isCustom?: boolean;
};

export const Button = (props: ButtonProps) => {
  const { isCustom } = props;
  const theme = useContext(ThemeContext);
  const style = isCustom
    ? customStyle
    : theme == "light"
    ? lightStyle
    : darkStyle;

  return (
    <button style={style} onClick={props.onClick}>
      {props.children}
    </button>
  );
};

Flexibility of `use`

The use API can be invoked conditionally and in loops.

As an example demonstrated below, we only read the value from the context if custom styling is disabled (isCustom is false).

Button.tsx

ThemeContext.tsx

App.tsx

const baseStyle = {
  borderRadius: "5px",
  transition: "all .2s",
};
const lightStyle = {
  ...baseStyle,
  background: "#fff",
  color: "#000",
};
const darkStyle = {
  ...baseStyle,
  background: "#000",
  color: "#fff",
};
const customStyle = {
  ...baseStyle,
  background:
    "linear-gradient(to right, red, orange, yellow, green, blue, indigo, violet)",
  color: "#fff",
};

import { ThemeContext } from "./ThemeContext";
import { use } from "react";

export type ButtonProps = {
  onClick: () => void;
  children: React.ReactNode;
  isCustom?: boolean;
};

export const Button = (props: ButtonProps) => {
  const { isCustom } = props;
  const style = isCustom
    ? customStyle
    : use(ThemeContext) == "light"
    ? lightStyle
    : darkStyle;

  return (
    <button style={style} onClick={props.onClick}>
      {props.children}
    </button>
  );
};

Limitation of `use`

use must be called from within the context of a React Component (either directly or from custom hooks).

As an example if you put this somewhere in the top level of your code you will get an error from React ESLint:

const value = use(ThemeContext);

The reason is that use still needs to resolve the passed context for some component. If you don't call use from a call stack that leads to a component, React cannot resolve the value for you.

This limitation is the same between use and useContext.

Transcript