Controllers

A controller exposes a board, target, or widget’s state and actions. Choose access based on where your code runs:

The examples in the access sections are excerpts. Insert your existing targets and widgets where indicated; they focus on how to obtain the controller.

Method 1: onfirstcreate callback

Components with controllers accept onfirstcreate. The callback receives the controller once. Use it to keep a reference for later actions. Timing depends on the adapter, as described below.

<script lang="ts">
	import { FlexiBoard, type FlexiBoardController } from '@flexiboards/svelte';

	let board = $state<FlexiBoardController>();

	function rememberBoard(controller: FlexiBoardController) {
		board = controller;
	}
</script>

<FlexiBoard onfirstcreate={rememberBoard}>
	<!-- ... -->
</FlexiBoard>

The callback runs during component setup, including SSR. Keep browser-only work in client event handlers or effects. Use initialLayout for data that must appear in the server-rendered board.

Method 2: bind:controller prop

Bind controller to a state variable when the parent needs the instance. Guard reads before initialization.

Here’s an example of using it to access the controller of a FlexiBoard:

<script lang="ts">
	import { FlexiBoard, type FlexiBoardController } from '@flexiboards/svelte';

	let boardController = $state<FlexiBoardController>();

	function clearBoard() {
		boardController?.clear();
	}
</script>

<button onclick={clearBoard}>Clear board</button>
<FlexiBoard bind:controller={boardController}>
	<!-- Existing targets and widgets. -->
</FlexiBoard>

The button handler runs on the client after initialization. For setup-time controller access, use onfirstcreate; for server-provided layout data, use initialLayout.

By the time the onfirstcreate callback fires, any variable bound to controller already holds the controller instance. If you prefer, you can read that variable rather than the controller parameter passed to the callback.

Method 3: context helper

From any component rendered inside a Flexiboards component, you can reach the surrounding widget’s controller through the getFlexiwidgetCtx() helper. It uses the Svelte Context API under the hood, so it must be called from the top level of a component.

<!-- my-widget-content.svelte -->
<script lang="ts">
	import { getFlexiwidgetCtx } from '@flexiboards/svelte';

	const widget = getFlexiwidgetCtx();
</script>

<div class:opacity-50={widget.isGrabbed}>...</div>

Changing the board from code

Once you hold a controller you can change the board without a drag. Placement actions run the grid rules. Successful layout mutations notify onLayoutChange; import and export have separate behavior shown below.

This excerpt assumes done and doing are target controllers from the same board:

// Move the first "done" card back into "doing", at the top.
const card = done.widgets.values().next().value;
card?.moveTo({ target: doing, x: 0, y: 0 });

moveTo bypasses canDrop. Validate application permissions before calling it; grid placement rules still apply. A refused move returns false. A successful placement notifies even if the coordinates are unchanged. Clears notify only if widgets are removed.

Reacting to interactions

Use canDrop for validation, grab and enter/leave callbacks for interaction progress, and drop/resize callbacks for committed changes. onLayoutChange reports the committed layout in a batched microtask before animations settle.

These configuration excerpts log accepted moves between targets and deletions. Keep your existing target declarations inside the board:

<script lang="ts">
	import { FlexiBoard, type FlexiBoardConfiguration } from '@flexiboards/svelte';

	const config: FlexiBoardConfiguration = {
		onWidgetDrop: ({ widget, sourceTarget, target }) => {
			if (sourceTarget !== target) {
				console.info('Moved', widget.userProvidedId ?? widget.id, 'to', target.key);
			}
		},
		onWidgetDelete: ({ widget }) => console.info('Deleted', widget.userProvidedId ?? widget.id),
		// Only the "done" column accepts cards that are marked complete.
		canDrop: ({ widget, target }) => target.key !== 'done' || widget.metadata?.complete === true
	};
</script>

<FlexiBoard {config}><!-- Existing targets and widgets. --></FlexiBoard>

canDrop runs alongside the grid’s own rules (bounds, collisions, size limits), which apply whether or not you provide it. A target’s own configuration can carry a canDrop too, for rules that belong to one list rather than the board; both must agree.

Controller APIs

Each controller’s properties and methods are listed on its component’s page: FlexiBoard, FlexiTarget, and FlexiWidget.