Actions

Where a button can go

.actions() declares them. Which builder you call decides where the button lands, and what the handler is given.

An action on the edit form shows while editing a row. It is never on the create screen, because there is no row yet.

One action

.actions(({ a, c, f }) => ({
	custom: [
		a.action({
			id: "publish",
			label: { en: "Publish", sk: "Publikovať" },
			icon: c.icon("ph:paper-plane-tilt"),
			form: {
				title: { en: "Publish this post" },
				fields: {
					note: f.textarea().label({ en: "Release note" }),
				},
			},
			confirmation: {
				title: { en: "Publish now?" },
				description: { en: "It goes live for everyone." },
			},
			handler: async ({ itemId, data, collections, queue }) => {
				await collections.posts.updateById({
					id: itemId!,
					data: { status: "published" },
				});
				await queue.notifySubscribers.publish({ note: data.note });
				return {
					type: "success",
					toast: { message: "Published" },
					effects: { invalidate: ["posts"] },
				};
			},
		}),
	],
}))

The Publish button now sits in the post's edit form. It asks for confirmation, then for a release note, then runs the handler on the server.

The definition

Give both a form and a confirmation and the confirmation comes first. The reader agrees, then fills the form in. Pick one.

Asking for input

form: {
	title: { en: "Send email" },
	description: { en: "Goes to every selected reader." },
	fields: {
		subject: f.text().label({ en: "Subject" }).required(),
		body: f.textarea().label({ en: "Body" }),
		priority: f.select([
			{ value: "low", label: { en: "Low" } },
			{ value: "high", label: { en: "High" } },
		]),
	},
	submitLabel: { en: "Send" },
	width: "lg",
}

fields is a record, not an array, and the keys are what land on data in the handler. The f here is not the field-name proxy from .list(). It builds a field, chainably, the way .fields() does. width is sm, md, lg or xl.

Confirming first

confirmation: {
	title: { en: "Delete every draft?" },
	description: { en: "This cannot be undone." },
	confirmLabel: { en: "Delete" },
	destructive: true,
}

Only title is required. destructive: true paints the confirm button red.

The handler

It runs on the server, inside the caller's session, in user access mode. So your .access() rules apply to anything it reads or writes.

The handler returns one of three results.

{ type: "success", toast: { message: "Done" }, effects: { … } }
{ type: "error", toast: { message: "Nope" }, errors: { subject: "Too long" } }
{ type: "redirect", url: "/preview/posts/1", external: true }

errors on an error result maps a form field to a message. A failed action can point at the input that caused it. A thrown exception becomes an error toast carrying the message, and the panel keeps working.

Effects

effects rides along on a success result.

type: "redirect" and effects.redirect both navigate. The difference is that a redirect result takes external: true and opens a new tab.

The built-in buttons

You declare none of these. They come from the client's own defaults.

Restore and Restore selected only show themselves on a row that has a deletedAt. Duplicate in the toolbar only shows when exactly one row is selected.

To change which ones show, use .list({ actions }). It replaces the default for each section you name. Declaring any custom action also clears the header default, so name Create again if you still want it. See The list.

The builtin key on .actions() is a different thing. It is the allowlist the executeAction route checks before it runs a built-in operation by name. It does not add or remove a button anywhere.

.actions(({ a }) => ({
	builtin: [a.create(), a.save(), a.delete()],
}))

Leave it unset and everything is allowed. That is create, save, delete, deleteMany, restore, restoreMany, duplicate, and the workflow transition. Naming a shorter list turns the rest into "action not found".

Access

Every action goes through one route, and that route requires session.user.role === "admin". The handler then runs under the caller's own session in user mode. A collection they cannot write still refuses them.

Admin config is not a permission boundary. Hiding a button hides a button. See Access control.

Where each topic lives

Next

Preview puts the page a row renders as next to the form that edits it.