User context

The User context is used to retrieve the active User object. This is most commonly used to display the user's profile information, like their name or email address.

The User context is a shortcut to the session.user property of the Clerk context.

The User object

The User object contains the following properties:

id

string

A unique identifier for the user.

firstName

string | null

The user's first name.

lastName

string | null

The user's last name.

fullName

string | null

The user's full name.

username

string | null

The user's username.

profileImageUrl

string | null

A url with the user's profile image.

primaryEmailAddress

EmailAddress | null

The EmailAddress object that the user has set as primary.

primaryEmailAddressID

string | null

The unique identifier for the EmailAddress that the user has set as primary.

emailAddresses

EmailAddress[]

Any array of all the EmailAddress objects associated with the user.

primaryPhoneNumber

PhoneNumber | null

The PhoneNumber object that the user has set as primary.

primaryPhoneNumberID

string | null

The unique identifier for the PhoneNumber that the user has set as primary.

phoneNumbers

PhoneNumber[]

Any array of all the PhoneNumber objects associated with the user.

externalAccounts

ExternalAccount[]

Any array of all the ExternalAccount objects associated with the user with OAuth.

passwordEnabled

boolean

A boolean indicating whether the user has a password on their account.

useUser (Hook)

Use the useUser hook to retrieve the User object from a function component. The hook can only be used from a descendant of SignedIn, the WithUser child function, or a component that uses withUser.

import { useUser } from "@clerk/clerk-react";
const Greeting = () => {
const user = useUser();
return (
<div>{user.firstName ? `Hello, ${user.firstName}!` : "Hello there!"}</div>
);
};

WithUser (Function-as-child)

Use the function-as-child pattern with WithUser to retrieve the User object within a class component.

import { WithUser } from "@clerk/clerk-react";
class Greeting extends React.Component {
render() {
return (
<WithUser>
{(user) => (
<div>
{user.firstName ? `Hello, ${user.firstName}!` : "Hello there!"}
</div>
)}
</WithUser>
);
}
}

withUser (Higher-order component)

Use the withUser higher-order component to pass the Clerk object as a prop to any component.

import { withUser } from "@clerk/clerk-react";
class Greeting extends React.Component {
render() {
return (
<div>
{this.props.user.firstName
? `Hello, ${this.props.user.firstName}!`
: "Hello there!"}
</div>
);
}
}
const GreetingWithUser = withUser(Greeting);

WithUserProp Typescript utility

In Typescript, use with WithUserProp utility type to make the compiler aware of the user prop.

import { withUser, WithUserProp } from "@clerk/clerk-react";
class Greeting extends React.Component<WithUserProp<{}>> {
render() {
return (
<div>
{this.props.user.firstName
? `Hello, ${this.props.user.firstName}!`
: "Hello there!"}
</div>
);
}
}
const GreetingWithUser = withUser(Greeting);