useUser

Access the User object inside of your components.

Overview

The useUser hook returns the current user state: { isLoaded, isSignedIn, user } . You can use the user object to access the currently active User. It can be used to update the user or display information about the user's profile, like their name or email address.

While hooks are the recommended way to use the Clerk APIs, If you don't wish to use React hooks we also offer a couple of alternative methods to retrieve the currently signed in user.

Usage

Retrieve the current user data

A basic example that showcases the useUser hook in action is a greeting component that greets the signed in user by their first name.

1
import { useUser } from "@clerk/clerk-react";
2

3
export default function Home() {
4
  const { isSignedIn, user, isLoaded } = useUser();
5

6
  if (!isLoaded) {
7
    return null;
8
  }
9

10
  if (isSignedIn) {
11
    return <div>Hello {user.fullName}!</div>;
12
  }
13

14
  return <div>Not signed in</div>;
15
}
16

Update the current user

Clerk provides a update function that allows you to update some of your users data

1
import { useUser } from "@clerk/clerk-react";
2

3
export default function Home() {
4
  const { user } = useUser();
5
  if (!user) return null;
6
  const updateUser = async () => {
7
    await user.update({
8
      firstName: "John",
9
      lastName: "Doe",
10
    });
11
  };
12
  return (
13
    <>
14
      <button onClick={updateUser}>Click me to update your name</button>
15
      <p>user.firstName: {user?.firstName}</p>
16
      <p>user.lastName: {user?.lastName}</p>
17
    </>
18
  );
19
}
20

Reload user data

In some circumstances you need retrieve the latest user data after updating your user in your backend. You can use user.reload() to reload the data on the frontend.

1
import { useUser } from "@clerk/clerk-react";
2

3
export default function Home() {
4
  const { user } = useUser();
5
  if (!user) return null;
6
  const updateUser = async () => {
7
    // updated data via an api point
8
    const updateMeta = await fetch("/api/updateMetadata");
9
    if (!updateMeta.message == "success") {
10
      throw new Error("Error updating");
11
    }
12
    user.reload();
13
  };
14
  return (
15
    <>
16
      <button onClick={updateUser}>Click me to update your metadata</button>
17
      <p>user role: {user?.publicMetadata.role}</p>
18
    </>
19
  );
20
}
21

Alternatives

There are times where using a hook might be inconvenient. For such cases, there are alternative ways to get access to the User object.

Clerk provides the <WithUser/> component and the withUser higher order component directive that will allow your wrapped components to get access to the currently signed in user.

withUser

The withUser function offers a Higher Order Component (HOC) that you can wrap your own components with, and they will have access to the active User object.

The User object will be accessible in the wrapped component under the user prop.

1
import { withUser } from "@clerk/clerk-react";
2

3
class Greeting extends React.Component {  
4
  render() {
5
    return (
6
      <div>
7
        {this.props.user.firstName
8
          ? `Hello ${this.props.user.firstName}!`
9
          : "Hello there!"}
10
      </div>
11
    );
12
  }
13
}
14

15
// Wrap your component with the withUser HOC.
16
export const GreetingWithUser = withUser(Greeting);

<WithUser />

If you really want to stretch JSX capabilities and you cannot use the withUser higher order component, we provide a <WithUser/> component that accepts a Function as a child. Inside this function, the active User object will be accessible.

1
import { WithUser } from "@clerk/clerk-react";
2

3
class Greeting extends React.Component {
4
  render() {
5
    return (
6
      <WithUser>
7
        {(user) => (
8
          <div>
9
            {user.firstName 
10
              ? `Hello, ${user.firstName}!` 
11
              : "Hello there!"}
12
          </div>
13
        )}
14
      </WithUser>
15
    );
16
  }
17
}

Usage with Typescript

If you're using Typescript, Clerk provides a WithUserProp type to make the compiler aware of the user prop for your components.

You can use the WithUserProp type in combination with both the withUser higher order component and the <WithUser/> component.

The example below uses the withUser higher order component.

1
import { withUser, WithUserProp } from "@clerk/clerk-react";
2

3
type GreetingProps = {
4
  greeting: string;
5
}
6

7
const Greeting = (props: WithUserProp<GreetingProps>) => {
8
  const { user, greeting } = props;
9
  return (
10
    <h1>{ greeting }</h1>
11
    <div>
12
      { user.firstName
13
        ? `Hello, ${user.firstName}!`
14
        : "Hello there!" }
15
    </div>
16
  );
17
}
18

19
export const GreetingWithUser = withUser(Greeting);