Data sources

• The key you declared is the key you query by. A block that declares issues calls useDataSource("issues").
• When connected to a host, initialization validates all declared data source bindings before rendering children.

​

Query rows

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

export function IssueBoard() {
	const { items, isLoading, hasMore, error } = useDataSource("issues", {
		limit: 100,
		filter: { key: "title", title: { is_not_empty: true } },
		sorts: [{ key: "title", direction: "ascending" }],
	})

	if (error) return <p role="alert">Could not load issues: {error.message}</p>
	if (isLoading) return <p>Loading issues…</p>
	if (items.length === 0) return <p>No matching issues.</p>

	return (
		<div>
			<ul>
				{items.map((item) => {
					const title = item.propertiesByKey.title
					return <li key={item.id}>{typeof title === "string" ? title : "Untitled"}</li>
				})}
			</ul>
			{hasMore && <p>More issues match this query. These results are incomplete.</p>}
		</div>
	)
}

​

Filters and sorting

filter: {
	key: "creator",
	created_by: {
		contains: { object: "user", id: "12345678-1234-4234-8234-123456789abc" },
	},
}

​

Query rows without React

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

await initCustomBlock()

const unsubscribe = customBlock.subscribeToDataSource({
	key: "issues",
	options: {
		limit: 100,
		filter: { key: "title", title: { is_not_empty: true } },
		sorts: [{ key: "title", direction: "ascending" }],
	},
	onSnapshot(snapshot) {
		if (snapshot.error) {
			console.error(snapshot.error.message)
			return
		}
		if (!snapshot.isLoading) console.log(snapshot.items)
	},
})

unsubscribe()

​

Keys versus IDs

​

Update a row

const result = await item.update({
	properties: {
		status: { type: "status", status: { name: "Done" } },
	},
})

if (result.status === "error") {
	console.error("Could not update issue:", result.error.message)
}

​

Archive and unarchive a row

​

Read the manifest at runtime

​

Property support

• Query result shows values in propertiesById and propertiesByKey from useDataSource and customBlock.subscribeToDataSource. Missing values can be undefined.
• Update row covers writes through item.update({ properties: ... }).
• Filter and Sort cover query options.
• 🟢 Supported: The SDK supports this operation in Notion.
• 🟡 Limited: The SDK supports this operation with the restrictions shown in the cell.
• 🔴 Unavailable: The SDK does not expose this operation.
• ⚫ Not supported in Notion: Notion itself does not support this operation in the stated case.

​

Notes

• Text values omit formatting, mention tokens, and annotations. A text fallback can be empty and does not preserve the property’s structured value. It does not provide structured formula or rollup results.
• Record pointers contain a table name and a record ID.
• People properties return record pointers with table values of notion_user, space_permission_group, bot, or organization_bot. Group IDs use the composite form groupId|workspaceId. People filters support users and groups. Bot and organization bot filtering is not supported.
• Every row includes four built-in properties in propertiesById: created_time, last_edited_time, created_by, and last_edited_by. The data source does not need matching schema properties. These values are read-only. Creator filters require an actual Created by schema property even though metadata reads do not. Timestamps use NotionDateTime in UTC. Creator and editor values use arrays of record pointers.
• The SDK accepts timestamp sorts, but the current Notion host requires a property ID in the data source’s actual schema. Sort using a configured created-time or last-edited-time property. The synthetic IDs created_time and last_edited_time alone are not sufficient.
• You can sort by up to 10 unique properties.
• Date-time filter values may include seconds or milliseconds, but the Notion host currently evaluates them at minute precision. Date filters do not expose relative dates or end-date targeting.
• Status filters accept option names and empty checks, but not status groups.
• Filters accept one condition or an and group of up to 25 conditions. The SDK does not support or or nested groups.
• Select, multi-select, and status query values contain option names. Their schemas provide option IDs and colors separately. Writes set the selected values. They do not edit option definitions or colors.

​

Writing values

item.propertiesByKey.status // "Done"

const result = await item.update({
  properties: {
    status: { type: "status", status: { name: "Done" } },
  },
});

if (result.status === "error") {
  console.error(result.error.message);
}

• Text: Title and rich text writes preserve plain text, but not formatting or mentions.
• Files: Supply external or existing hosted file URLs. The host stores them as links and does not support upload references.
• Relations: Supply the complete replacement list of related pages. The host rejects has_more: true, which indicates an incomplete list.