Skip to content
a tiny (4kb) React hook for using Netlify Identity, no UI
Branch: master
Clone or download
sw-yx Bump safer-eval from 1.3.3 to 1.3.5 in /examples/example-reach-ro… (#23)
Bump safer-eval from 1.3.3 to 1.3.5 in /examples/example-reach-router
Latest commit 155257e Oct 21, 2019


Netlify Identity + React Hooks, with Typescript. Bring your own UI!

NPM JavaScript Style Guide

Use Netlify Identity easier with React! This is a thin wrapper over the gotrue-js library for easily accessing Netlify Identity functionality in your app, with React Context and Hooks. Types are provided.

Three demos:

This library is not officially maintained by Netlify. This is written by swyx for his own use (and others with like minds 😎) and will be maintained as a personal project unless formally adopted by Netlify. See below for official alternatives.


List of Alternatives

Lowest level JS Library: If you want to use the official Javascript bindings to GoTrue, Netlify's underlying Identity service written in Go, use

React bindings: If you want a thin wrapper over Gotrue-js for React, react-netlify-identity is a "headless" library, meaning there is no UI exported and you will write your own UI to work with the authentication. If you want a drop-in UI, there is yet another library that wraps react-netlify-identity:

High level overlay: If you want a "widget" overlay that gives you a nice UI out of the box, with a somewhat larger bundle, check

High level popup: If you want a popup window approach also with a nice UI out of the box, and don't mind the popup flow, check


Library is written in Typescript. File an issue if you find any problems.


yarn add react-netlify-identity


⚠️ Important: You will need to have an active Netlify site running with Netlify Identity turned on. Click here for instructions to get started/double check that it is on. We will need your site's url (e.g. to initialize IdentityContextProvider.

When you call useIdentityContext(), you can destructure these variables and methods:

  • user: User
  • setUser: directly set the user object. Not advised; use carefully!! mostly you should use the methods below
  • isConfirmedUser: boolean: if they have confirmed their email
  • isLoggedIn: boolean: if the user is logged in
  • signupUser(email: string, password: string, data: Object)
  • loginUser(email: string, password: string, remember: Boolean) - we default the remember term to true since you'll usually want to remember the session in localStorage. set it to false if you need to
  • logoutUser()
  • requestPasswordRecovery(email: string)
  • recoverAccount(token: string, remember?: boolean | undefined)
  • updateUser(fields: { data: object })
  • getFreshJWT()
  • authedFetch(endpoint: string, obj = {}) (a thin axios-like wrapper over fetch that has the user's JWT attached, for convenience pinging Netlify Functions with Netlify Identity)
import React from 'react';

import { IdentityContextProvider } from 'react-netlify-identity';

function App() {
  const url = ''; // supply the url of your Netlify site instance. VERY IMPORTANT. no point putting in env var since this is public anyway
  return (
    <IdentityContextProvider url={url}>
      {/* rest of your app */}

Click for More Example code

import { useIdentityContext } from 'react-netlify-identity';

// log in/sign up example
function Login() {
  const { loginUser, signupUser } = useIdentityContext();
  const formRef = React.useRef();
  const [msg, setMsg] = React.useState('');
  const signup = () => {
    const email =;
    const password = formRef.current.password.value;
    signupUser(email, password)
      .then(user => {
        console.log('Success! Signed up', user);
      .catch(err => console.error(err) || setMsg('Error: ' + err.message));
  return (
      onSubmit={e => {
        const email =;
        const password =;
        load(loginUser(email, password, true))
          .then(user => {
            console.log('Success! Logged in', user);
          .catch(err => console.error(err) || setMsg('Error: ' + err.message));
          <input type="email" name="email" />
          <input type="password" name="password" />
        <input type="submit" value="Log in" />
        <button onClick={signup}>Sign Up </button>
        {msg && <pre>{msg}</pre>}

// log out user
function Logout() {
  const { logoutUser } = useIdentityContext();
  return <button onClick={logoutUser}>You are signed in. Log Out</button>;

// check `identity.user` in a protected route
function PrivateRoute(props) {
  const identity = useIdentityContext();
  let { as: Comp, } = props;
  return identity.user ? (
    <Comp {} />
  ) : (
      <h3>You are trying to view a protected page. Please log in</h3>
      <Login />

// check if user has confirmed their email
// use authedFetch API to make a request to Netlify Function with the user's JWT token,
// letting your function use the `user` object
function Dashboard() {
  const { isConfirmedUser, authedFetch } = useIdentityContext();
  const [msg, setMsg] = React.useState('Click to load something');
  const handler = () => {
  return (
      <h3>This is a Protected Dashboard!</h3>
      {!isConfirmedUser && (
        <pre style={{ backgroundColor: 'papayawhip' }}>
          You have not confirmed your email. Please confirm it before you ping
          the API.
      <hr />
        <p>You can try pinging our authenticated API here.</p>
          If you are logged in, you should be able to see a `user` info here.
        <button onClick={handler}>Ping authenticated API</button>
        <pre>{JSON.stringify(msg, null, 2)}</pre>

Lower level API: useNetlifyIdentity

If you'd like to handle your own context yourself, you can use this library as a hook as well:

function useNetlifyIdentity(
  url: string,
  onAuthChange: authChangeParam = () => {},
  enableRunRoutes: boolean = true
): ReactNetlifyIdentityAPI;

the library watches for and handles confirmation routes by default. If you don't like this, pass enableRunRoutes: false. This was added here in v0.1.8


MIT © sw-yx

You can’t perform that action at this time.