[9:59 AM] 9:59 AM Meeting ended: 1h 15m 32s

[10:14 AM] Holly, Joshua Randel

there are CTA's across the site that would also need that text to be picked up and translated

\

This page describes the APIs for the built-in Hooks in React.

If you’re new to Hooks, you might want to check out the overview first. You may also find useful information in the frequently asked questions section.

• Basic Hooks

  • useState

  • useEffect

Basic Hooks

useState

Returns a stateful value, and a function to update it.

During the initial render, the returned state (state) is the same as the value passed as the first argument (initialState).

The setState function is used to update the state. It accepts a new state value and enqueues a re-render of the component.

During subsequent re-renders, the first value returned by useState will always be the most recent state after applying updates.

Note

React guarantees that setState function identity is stable and won’t change on re-renders. This is why it’s safe to omit from the useEffect or useCallback dependency list.

Functional updates

If the new state is computed using the previous state, you can pass a function to setState. The function will receive the previous value, and return an updated value. Here’s an example of a counter component that uses both forms of setState:

The ”+” and ”-” buttons use the functional form, because the updated value is based on the previous value. But the “Reset” button uses the normal form, because it always sets the count back to the initial value.

If your update function returns the exact same value as the current state, the subsequent rerender will be skipped completely.

Note

Unlike the setState method found in class components, useState does not automatically merge update objects. You can replicate this behavior by combining the function updater form with object spread syntax:

Another option is useReducer, which is more suited for managing state objects that contain multiple sub-values.

Lazy initial state

The initialState argument is the state used during the initial render. In subsequent renders, it is disregarded. If the initial state is the result of an expensive computation, you may provide a function instead, which will be executed only on the initial render:

Bailing out of a state update

If you update a State Hook to the same value as the current state, React will bail out without rendering the children or firing effects. (React uses the Object.is comparison algorithm.)

Note that React may still need to render that specific component again before bailing out. That shouldn’t be a concern because React won’t unnecessarily go “deeper” into the tree. If you’re doing expensive calculations while rendering, you can optimize them with useMemo.

useEffect

Accepts a function that contains imperative, possibly effectful code.

Mutations, subscriptions, timers, logging, and other side effects are not allowed inside the main body of a function component (referred to as React’s render phase). Doing so will lead to confusing bugs and inconsistencies in the UI.

Instead, use useEffect. The function passed to useEffect will run after the render is committed to the screen. Think of effects as an escape hatch from React’s purely functional world into the imperative world.

By default, effects run after every completed render, but you can choose to fire them only when certain values have changed.

Cleaning up an effect

Often, effects create resources that need to be cleaned up before the component leaves the screen, such as a subscription or timer ID. To do this, the function passed to useEffect may return a clean-up function. For example, to create a subscription:

The clean-up function runs before the component is removed from the UI to prevent memory leaks. Additionally, if a component renders multiple times (as they typically do), the previous effect is cleaned up before executing the next effect. In our example, this means a new subscription is created on every update. To avoid firing an effect on every update, refer to the next section.

Timing of effects

Unlike componentDidMount and componentDidUpdate, the function passed to useEffect fires after layout and paint, during a deferred event. This makes it suitable for the many common side effects, like setting up subscriptions and event handlers, because most types of work shouldn’t block the browser from updating the screen.

However, not all effects can be deferred. For example, a DOM mutation that is visible to the user must fire synchronously before the next paint so that the user does not perceive a visual inconsistency. (The distinction is conceptually similar to passive versus active event listeners.) For these types of effects, React provides one additional Hook called useLayoutEffect. It has the same signature as useEffect, and only differs in when it is fired.

Although useEffect is deferred until after the browser has painted, it’s guaranteed to fire before any new renders. React will always flush a previous render’s effects before starting a new update.

Conditionally firing an effect

The default behavior for effects is to fire the effect after every completed render. That way an effect is always recreated if one of its dependencies changes.

However, this may be overkill in some cases, like the subscription example from the previous section. We don’t need to create a new subscription on every update, only if the source prop has changed.

To implement this, pass a second argument to useEffect that is the array of values that the effect depends on. Our updated example now looks like this:

Now the subscription will only be recreated when props.source changes.

Note

If you use this optimization, make sure the array includes all values from the component scope (such as props and state) that change over time and that are used by the effect. Otherwise, your code will reference stale values from previous renders. Learn more about how to deal with functions and what to do when the array values change too often.

If you want to run an effect and clean it up only once (on mount and unmount), you can pass an empty array ([]) as a second argument. This tells React that your effect doesn’t depend on any values from props or state, so it never needs to re-run. This isn’t handled as a special case — it follows directly from how the dependencies array always works.

If you pass an empty array ([]), the props and state inside the effect will always have their initial values. While passing [] as the second argument is closer to the familiar componentDidMount and componentWillUnmount mental model, there are usually to avoid re-running effects too often. Also, don’t forget that React defers running useEffect until after the browser has painted, so doing extra work is less of a problem.

We recommend using the rule as part of our package. It warns when dependencies are specified incorrectly and suggests a fix.

The array of dependencies is not passed as arguments to the effect function. Conceptually, though, that’s what they represent: every value referenced inside the effect function should also appear in the dependencies array. In the future, a sufficiently advanced compiler could create this array automatically.

useContext

Accepts a context object (the value returned from React.createContext) and returns the current context value for that context. The current context value is determined by the value prop of the nearest <MyContext.Provider> above the calling component in the tree.

When the nearest <MyContext.Provider> above the component updates, this Hook will trigger a rerender with the latest context value passed to that MyContext provider. Even if an ancestor uses React.memo or shouldComponentUpdate, a rerender will still happen starting at the component itself using useContext.

Don’t forget that the argument to useContext must be the context object itself:

• Correct: useContext(MyContext)

• Incorrect: useContext(MyContext.Consumer)

• Incorrect: useContext(MyContext.Provider)

A component calling useContext will always re-render when the context value changes. If re-rendering the component is expensive, you can optimize it by using memoization.

Tip

If you’re familiar with the context API before Hooks, useContext(MyContext) is equivalent to static contextType = MyContext in a class, or to <MyContext.Consumer>.

useContext(MyContext) only lets you read the context and subscribe to its changes. You still need a <MyContext.Provider> above in the tree to provide the value for this context.

Putting it together with Context.Provider

This example is modified for hooks from a previous example in the Context Advanced Guide, where you can find more information about when and how to use Context.

Additional Hooks

The following Hooks are either variants of the basic ones from the previous section, or only needed for specific edge cases. Don’t stress about learning them up front.

useReducer

An alternative to useState. Accepts a reducer of type (state, action) => newState, and returns the current state paired with a dispatch method. (If you’re familiar with Redux, you already know how this works.)

useReducer is usually preferable to useState when you have complex state logic that involves multiple sub-values or when the next state depends on the previous one. useReducer also lets you optimize performance for components that trigger deep updates because you can pass dispatch down instead of callbacks.

Here’s the counter example from the useState section, rewritten to use a reducer:

Note

React guarantees that dispatch function identity is stable and won’t change on re-renders. This is why it’s safe to omit from the useEffect or useCallback dependency list.

Specifying the initial state

There are two different ways to initialize useReducer state. You may choose either one depending on the use case. The simplest way is to pass the initial state as a second argument:

Note

React doesn’t use the state = initialState argument convention popularized by Redux. The initial value sometimes needs to depend on props and so is specified from the Hook call instead. If you feel strongly about this, you can call useReducer(reducer, undefined, reducer) to emulate the Redux behavior, but it’s not encouraged.

Lazy initialization

You can also create the initial state lazily. To do this, you can pass an init function as the third argument. The initial state will be set to init(initialArg).

It lets you extract the logic for calculating the initial state outside the reducer. This is also handy for resetting the state later in response to an action:

Bailing out of a dispatch

If you return the same value from a Reducer Hook as the current state, React will bail out without rendering the children or firing effects. (React uses the Object.is comparison algorithm.)

Note that React may still need to render that specific component again before bailing out. That shouldn’t be a concern because React won’t unnecessarily go “deeper” into the tree. If you’re doing expensive calculations while rendering, you can optimize them with useMemo.

useCallback

Returns a memoized callback.

Pass an inline callback and an array of dependencies. useCallback will return a memoized version of the callback that only changes if one of the dependencies has changed. This is useful when passing callbacks to optimized child components that rely on reference equality to prevent unnecessary renders (e.g. shouldComponentUpdate).

useCallback(fn, deps) is equivalent to useMemo(() => fn, deps).

Note

The array of dependencies is not passed as arguments to the callback. Conceptually, though, that’s what they represent: every value referenced inside the callback should also appear in the dependencies array. In the future, a sufficiently advanced compiler could create this array automatically.

We recommend using the exhaustive-deps rule as part of our eslint-plugin-react-hooks package. It warns when dependencies are specified incorrectly and suggests a fix.

useMemo

Returns a memoized value.

Pass a “create” function and an array of dependencies. useMemo will only recompute the memoized value when one of the dependencies has changed. This optimization helps to avoid expensive calculations on every render.

Remember that the function passed to useMemo runs during rendering. Don’t do anything there that you wouldn’t normally do while rendering. For example, side effects belong in useEffect, not useMemo.

If no array is provided, a new value will be computed on every render.

You may rely on useMemo as a performance optimization, not as a semantic guarantee. In the future, React may choose to “forget” some previously memoized values and recalculate them on next render, e.g. to free memory for offscreen components. Write your code so that it still works without useMemo — and then add it to optimize performance.

Note

The array of dependencies is not passed as arguments to the function. Conceptually, though, that’s what they represent: every value referenced inside the function should also appear in the dependencies array. In the future, a sufficiently advanced compiler could create this array automatically.

We recommend using the exhaustive-deps rule as part of our eslint-plugin-react-hooks package. It warns when dependencies are specified incorrectly and suggests a fix.

useRef

useRef returns a mutable ref object whose .current property is initialized to the passed argument (initialValue). The returned object will persist for the full lifetime of the component.

A common use case is to access a child imperatively:

Essentially, useRef is like a “box” that can hold a mutable value in its .current property.

You might be familiar with refs primarily as a way to access the DOM. If you pass a ref object to React with <div ref={myRef} />, React will set its .current property to the corresponding DOM node whenever that node changes.

However, useRef() is useful for more than the ref attribute. It’s handy for keeping any mutable value around similar to how you’d use instance fields in classes.

This works because useRef() creates a plain JavaScript object. The only difference between useRef() and creating a {current: ...} object yourself is that useRef will give you the same ref object on every render.

Keep in mind that useRef doesn’t notify you when its content changes. Mutating the .current property doesn’t cause a re-render. If you want to run some code when React attaches or detaches a ref to a DOM node, you may want to use a callback ref instead.

useImperativeHandle

useImperativeHandle customizes the instance value that is exposed to parent components when using ref. As always, imperative code using refs should be avoided in most cases. useImperativeHandle should be used with forwardRef:

In this example, a parent component that renders <FancyInput ref={inputRef} /> would be able to call inputRef.current.focus().

useLayoutEffect

The signature is identical to useEffect, but it fires synchronously after all DOM mutations. Use this to read layout from the DOM and synchronously re-render. Updates scheduled inside useLayoutEffect will be flushed synchronously, before the browser has a chance to paint.

Prefer the standard useEffect when possible to avoid blocking visual updates.

Tip

If you’re migrating code from a class component, note useLayoutEffect fires in the same phase as componentDidMount and componentDidUpdate. However, we recommend starting with useEffect first and only trying useLayoutEffect if that causes a problem.

If you use server rendering, keep in mind that neither useLayoutEffect nor useEffect can run until the JavaScript is downloaded. This is why React warns when a server-rendered component contains useLayoutEffect. To fix this, either move that logic to useEffect (if it isn’t necessary for the first render), or delay showing that component until after the client renders (if the HTML looks broken until useLayoutEffect runs).

To exclude a component that needs layout effects from the server-rendered HTML, render it conditionally with showChild && <Child /> and defer showing it with useEffect(() => { setShowChild(true); }, []). This way, the UI doesn’t appear broken before hydration.

useDebugValue

useDebugValue can be used to display a label for custom hooks in React DevTools.

For example, consider the useFriendStatus custom Hook described in “Building Your Own Hooks”:

Tip

We don’t recommend adding debug values to every custom Hook. It’s most valuable for custom Hooks that are part of shared libraries.

Defer formatting debug values

In some cases formatting a value for display might be an expensive operation. It’s also unnecessary unless a Hook is actually inspected.

For this reason useDebugValue accepts a formatting function as an optional second parameter. This function is only called if the Hooks are inspected. It receives the debug value as a parameter and should return a formatted display value.

For example a custom Hook that returned a Date value could avoid calling the toDateString function unnecessarily by passing the following formatter:

\

[Yesterday 8:22 AM] Holly, Joshua Randel

\

[Yesterday 8:26 AM] Evanoff, Matthew

... Holly, Joshua Randel are you saying it isn't my changes?

\

[Yesterday 8:33 AM] Holly, Joshua Randel

the legacy start service, application component driven, form is failing as well. I don't think your changes broke submission

like 1

useMemo

• unmount function to unmount the component

• container reference to the DOM node where the component is mounted

• all the queries from DOM Testing Library, bound to the document so there is no need to pass a node as the first argument (usually, you can use the screen import instead)

If you're looking to convert a React project, we recommend looking at the React Conversion Guide first.

Setting up your Directories

If you're writing in plain JavaScript, it's likely that you're running your JavaScript directly, where your .js files are in a src, lib, or dist directory, and then ran as desired.

If that's the case, the files that you've written are going to be used as inputs to TypeScript, and you'll run the outputs it produces. During our JS to TS migration, we'll need to separate our input files to prevent TypeScript from overwriting them. If your output files need to reside in a specific directory, then that will be your output directory.

You might also be running some intermediate steps on your JavaScript, such as bundling or using another transpiler like Babel. In this case, you might already have a folder structure like this set up.

From this point on, we're going to assume that your directory is set up something like this:

If you have a tests folder outside of your src directory, you might have one tsconfig.json in src, and one in tests as well.

Writing a Configuration File

TypeScript uses a file called tsconfig.json for managing your project's options, such as which files you want to include, and what sorts of checking you want to perform. Let's create a bare-bones one for our project:

Here we're specifying a few things to TypeScript:

1. Read in any files it understands in the src directory (with include).

2. Accept JavaScript files as inputs (with allowJs).

3. Emit all of the output files in built (with ).

4. Translate newer JavaScript constructs down to an older version like ECMAScript 5 (using ).

At this point, if you try running tsc at the root of your project, you should see output files in the built directory. The layout of files in built should look identical to the layout of src. You should now have TypeScript working with your project.

Early Benefits

Even at this point you can get some great benefits from TypeScript understanding your project. If you open up an editor like VS Code or Visual Studio, you'll see that you can often get some tooling support like completion. You can also catch certain bugs with options like:

• noImplicitReturns which prevents you from forgetting to return at the end of a function.

• noFallthroughCasesInSwitch which is helpful if you never want to forget a break statement between cases in a switch block.

TypeScript will also warn about unreachable code and labels, which you can disable with allowUnreachableCode and allowUnusedLabels respectively.

You might have some more build steps in your pipeline. Perhaps you concatenate something to each of your files. Each build tool is different, but we'll do our best to cover the gist of things.

Gulp

If you're using Gulp in some fashion, we have a tutorial on using Gulp with TypeScript, and integrating with common build tools like Browserify, Babelify, and Uglify. You can read more there.

Webpack

Webpack integration is pretty simple. You can use ts-loader, a TypeScript loader, combined with source-map-loader for easier debugging. Simply run

and merge in options from the following into your webpack.config.js file:

It's important to note that ts-loader will need to run before any other loader that deals with .js files.

The same goes for awesome-typescript-loader, another TypeScript loader for Webpack. You can read more about the differences between the two here.

You can see an example of using Webpack in our tutorial on React and Webpack.

Moving to TypeScript Files

At this point, you're probably ready to start using TypeScript files. The first step is to rename one of your .js files to .ts. If your file uses JSX, you'll need to rename it to .tsx.

Finished with that step? Great! You've successfully migrated a file from JavaScript to TypeScript!

Of course, that might not feel right. If you open that file in an editor with TypeScript support (or if you run tsc --pretty), you might see red squiggles on certain lines. You should think of these the same way you'd think of red squiggles in an editor like Microsoft Word. TypeScript will still translate your code, just like Word will still let you print your documents.

If that sounds too lax for you, you can tighten that behavior up. If, for instance, you don't want TypeScript to compile to JavaScript in the face of errors, you can use the noEmitOnError option. In that sense, TypeScript has a dial on its strictness, and you can turn that knob up as high as you want.

If you plan on using the stricter settings that are available, it's best to turn them on now (see Getting Stricter Checks below). For instance, if you never want TypeScript to silently infer any for a type without you explicitly saying so, you can use noImplicitAny before you start modifying your files. While it might feel somewhat overwhelming, the long-term gains become apparent much more quickly.

Weeding out Errors

Like we mentioned, it's not unexpected to get error messages after conversion. The important thing is to actually go one by one through these and decide how to deal with the errors. Often these will be legitimate bugs, but sometimes you'll have to explain what you're trying to do a little better to TypeScript.

Importing from Modules

You might start out getting a bunch of errors like Cannot find name 'require'., and Cannot find name 'define'.. In these cases, it's likely that you're using modules. While you can just convince TypeScript that these exist by writing out

or

it's better to get rid of those calls and use TypeScript syntax for imports.

First, you'll need to enable some module system by setting TypeScript's module option. Valid options are commonjs, amd, system, and umd.

If you had the following Node/CommonJS code:

or the following RequireJS/AMD code:

then you would write the following TypeScript code:

Getting Declaration Files

If you started converting over to TypeScript imports, you'll probably run into errors like Cannot find module 'foo'.. The issue here is that you likely don't have declaration files to describe your library. Luckily this is pretty easy. If TypeScript complains about a package like lodash, you can just write

If you're using a module option other than commonjs, you'll need to set your moduleResolution option to node.

After that, you'll be able to import lodash with no issues, and get accurate completions.

Exporting from Modules

Typically, exporting from a module involves adding properties to a value like exports or module.exports. TypeScript allows you to use top-level export statements. For instance, if you exported a function like so:

you could write that out as the following:

Sometimes you'll entirely overwrite the exports object. This is a common pattern people use to make their modules immediately callable like in this snippet:

You might have previously written that like so:

In TypeScript, you can model this with the export = construct.

Too many/too few arguments

You'll sometimes find yourself calling a function with too many/few arguments. Typically, this is a bug, but in some cases, you might have declared a function that uses the arguments object instead of writing out any parameters:

In this case, we need to use TypeScript to tell any of our callers about the ways myCoolFunction can be called using function overloads.

We added two overload signatures to myCoolFunction. The first checks states that myCoolFunction takes a function (which takes a number), and then a list of numbers. The second one says that it will take a function as well, and then uses a rest parameter (...nums) to state that any number of arguments after that need to be numbers.

Sequentially Added Properties

Some people find it more aesthetically pleasing to create an object and add properties immediately after like so:

TypeScript will say that you can't assign to color and volume because it first figured out the type of options as {} which doesn't have any properties. If you instead moved the declarations into the object literal themselves, you'd get no errors:

You could also define the type of options and add a type assertion on the object literal.

Alternatively, you can just say options has the type any which is the easiest thing to do, but which will benefit you the least.

any, Object, and {}

You might be tempted to use Object or {} to say that a value can have any property on it because Object is, for most purposes, the most general type. However any is actually the type you want to use in those situations, since it's the most flexible type.

For instance, if you have something that's typed as Object you won't be able to call methods like toLowerCase() on it. Being more general usually means you can do less with a type, but any is special in that it is the most general type while still allowing you to do anything with it. That means you can call it, construct it, access properties on it, etc. Keep in mind though, whenever you use any, you lose out on most of the error checking and editor support that TypeScript gives you.

If a decision ever comes down to Object and {}, you should prefer {}. While they are mostly the same, technically {} is a more general type than Object in certain esoteric cases.

Getting Stricter Checks

TypeScript comes with certain checks to give you more safety and analysis of your program. Once you've converted your codebase to TypeScript, you can start enabling these checks for greater safety.

No Implicit any

There are certain cases where TypeScript can't figure out what certain types should be. To be as lenient as possible, it will decide to use the type any in its place. While this is great for migration, using any means that you're not getting any type safety, and you won't get the same tooling support you'd get elsewhere. You can tell TypeScript to flag these locations down and give an error with the noImplicitAny option.

Strict null & undefined Checks

By default, TypeScript assumes that null and undefined are in the domain of every type. That means anything declared with the type number could be null or undefined. Since null and undefined are such a frequent source of bugs in JavaScript and TypeScript, TypeScript has the strictNullChecks option to spare you the stress of worrying about these issues.

When strictNullChecks is enabled, null and undefined get their own types called null and undefined respectively. Whenever anything is possibly null, you can use a union type with the original type. So for instance, if something could be a number or null, you'd write the type out as number | null.

If you ever have a value that TypeScript thinks is possibly null/undefined, but you know better, you can use the postfix ! operator to tell it otherwise.

As a heads up, when using strictNullChecks, your dependencies may need to be updated to use strictNullChecks as well.

No Implicit any for this

When you use the this keyword outside of classes, it has the type any by default. For instance, imagine a Point class, and imagine a function that we wish to add as a method:

This has the same problems we mentioned above - we could easily have misspelled getDistance and not gotten an error. For this reason, TypeScript has the noImplicitThis option. When that option is set, TypeScript will issue an error when this is used without an explicit (or inferred) type. The fix is to use a this-parameter to give an explicit type in the interface or in the function itself: