Users

Custom blocks are in private alpha:

Do not discuss publicly or share with anyone outside your workspace.
Access must be enabled per workspace. Installing the SDK does not grant access.
These APIs may experience breaking changes without notice.

The current user

customBlock.getCurrentUser() and useCurrentUser() return the user viewing the custom block. Both read the user from the block’s state without a separate request. Wait for initCustomBlock() to resolve before calling the getter or mounting components that use the hook. See initialization.

TypeScript API

Use customBlock.getCurrentUser() to read the current user in any framework. Subscribe to context changes to keep your UI updated:

import { customBlock, initCustomBlock } from "@notionhq/custom-blocks"

await initCustomBlock()
const user = customBlock.getCurrentUser()
console.log(user.name)

const unsubscribe = customBlock.subscribe(() => {
	const nextUser = customBlock.getCurrentUser()
	console.log(nextUser.name)
})

Call unsubscribe() when you no longer need updates. The callback can run even when the current user has not changed.

React hook

In React, use useCurrentUser() to re-render when the current user changes:

import { useCurrentUser } from "@notionhq/custom-blocks/react"

function Greeting() {
	const user = useCurrentUser()
	return <p>Hello, {user.name ?? "there"}</p>
}

Both approaches return the same NotionUser shape.

User object

NotionUser is based on the public API User object. users.get() and the current-user APIs return a NotionUser. users.list() returns a page of these objects. Custom blocks return only people, not bots or integrations. All fields except name are always present. name may be omitted. avatar_url is present but can be null.

Property	Type	Description
`object`	`"user"`	Identifies a user object.
`id`	`string` (UUID)	The user’s ID. Typed as `NotionUserId` in the SDK.
`name`	`string` (optional)	The user’s name, if available.
`avatar_url`	`string` (nullable)	The user’s avatar URL, or `null` if no avatar is available.
`type`	`"person"`	Custom blocks return people.
`person`	`object`	The user’s person details.
`person.email`	`string`	The user’s email address.

List users

Each users.list() call returns one page of workspace users visible to the viewing user. The SDK does not fetch the remaining pages automatically.

import { users } from "@notionhq/custom-blocks"

const result = await users.list({ pageSize: 50 })

if (result.status === "success") {
	for (const user of result.list.results) {
		console.log(user.id, user.name, user.person.email)
	}
}

Option	Description
`pageSize`	Maximum users per response. Optional integer from 1 to 100. Defaults to 100.
`startCursor`	Optional cursor from the previous response’s `next_cursor`. Omit it for the first page.

Pass next_cursor as startCursor to request the next page. Use the cursor exactly as returned. Do not parse it or create your own. Stop when has_more is false.

import { users, type ListUsersArgs } from "@notionhq/custom-blocks"

const args: ListUsersArgs = { pageSize: 50 }

while (true) {
	const result = await users.list(args)
	if (result.status === "error") {
		console.error(result.error)
		break
	}

	for (const user of result.list.results) {
		console.log(user.id, user.name)
	}

	if (!result.list.has_more || result.list.next_cursor === null) break
	args.startCursor = result.list.next_cursor
}

Get a user

import { customBlock, users } from "@notionhq/custom-blocks"

// After initialization, use the current user’s ID for this example.
const userId = customBlock.getCurrentUser().id
const result = await users.get(userId)

if (result.status === "success") {
	console.log(result.user.name)
} else {
	console.error(result.error)
}

On success, result.user is a NotionUser. A people property can contain both users and groups (object: "group"). users.get() and users.list() only support people. You cannot use these APIs to resolve a group or list its members. Skip group entries when you need a person’s name and avatar. Match the person’s ID against results from users.list(). Reuse those results if your UI already lists workspace users. IDs in a people property are plain strings. users.get() requires a NotionUserId, such as an ID from the user APIs.

Permissions

A user returned by users.list() does not necessarily have access to the current page or data source. Do not use this list to check page or data source permissions. If a request returns status: "error", handle the error before reading result.user or result.list. See error handling.

Get started

Guides

Workers SDK reference

Custom blocks SDK reference

CLI reference

The current user

TypeScript API

React hook

User object

List users

Get a user

Permissions

​The current user

​TypeScript API

​React hook

​User object

​List users

​Get a user

​Permissions

The current user

TypeScript API

React hook

User object

List users

Get a user

Permissions