Define where apps render

A slot is a named place for UI. It might be a side panel, part of a navbar, or a whole page. The green areas below are two slots:

An app wireframe with a navbar slot and a side panel slot highlighted in green.

Define slots

Give each area a name in your contract. This defines the two slots in the picture:

Zod
ArkType
Valibot

patchsmith.ts

import { defineContract } from "patchsmith";
import { z } from "zod";

export const contract = defineContract({
  views: { "/": z.object({}) },
  slots: {
    navbar: { views: ["/"] },
    panel: { views: ["/"] },
  },
});

patchsmith.ts

import { defineContract } from "patchsmith";
import { type } from "arktype";

export const contract = defineContract({
  views: { "/": type({}) },
  slots: {
    navbar: { views: ["/"] },
    panel: { views: ["/"] },
  },
});

patchsmith.ts

import { defineContract } from "patchsmith";
import * as v from "valibot";

export const contract = defineContract({
  views: { "/": v.object({}) },
  slots: {
    navbar: { views: ["/"] },
    panel: { views: ["/"] },
  },
});

Include / in a slot’s views so apps can provide default UI when no more specific view matches.

Describe the space

Use description to tell app authors and agents where a slot appears:

Inside your contract's slots

panel: {
  views: ["/"],
  description: "Right-hand side panel with independently scrolling content.",
},
page: {
  views: ["/"],
  description: "Main content area beside the host navigation.",
},

Agents read descriptions in the generated slot documentation while building apps. Your host controls the actual layout and dimensions.

Describe the slot’s usable width and height at each breakpoint, including any padding or scrolling behavior. For example: “360 px wide on desktop, full width below 768 px, with independent scrolling.” This helps agents choose layouts that fit the available space.

Allow multiple slot instances

By default, a slot has one instance per app, showing one view at a time. Set multiple: true when you want separate instances that can appear together. Use multiple instances for tiles or pages that need separate metadata:

Slot	Instances	Metadata could describe
Dashboard tile	A chart, a task list, and a summary	Each tile’s position and size
Page	Reports, activity, and settings pages	A label and icon for each page’s sidebar link

One app can supply all of these instances. Each has its own key, metadata, and data. Tiles can appear together; page instances can each have a link and open separately.

Inside your contract's slots

tile: { views: ["/"], multiple: true },
page: { views: ["/"], multiple: true },

For example, two page instances could have this metadata:

Page instances

[
  {
    "key": "reports",
    "metadata": { "label": "Reports", "icon": "chart" },
    "data": {}
  },
  {
    "key": "activity",
    "metadata": { "label": "Activity", "icon": "clock" },
    "data": {}
  }
]

Metadata lets you decide how to arrange tiles or build links. Patchsmith doesn’t automatically position tiles or create routes from it.

Context chooses the view

A panel can show an overview on a members list and details when a member is open. The slot selects the closest available view for the current context. Views change the UI inside an instance. The multiple option lets an app supply separate instances. To supply UI and instances from an app, see Write app UI.

SDK reference

Slots live in defineContract({ slots }), keyed by the names you choose.

Field	Type	Meaning
`views`	`readonly string[]`	Required. Context paths declared in the contract’s `views`.
`description`	`string`	Optional. Layout and sizing guidance for app authors and agents. Does not enforce dimensions.
`multiple`	`boolean`	Defaults to `false`. Set to `true` to allow independent instances from one app.

export type SlotDefinitions<TPath extends string = string> = Record<
  string,
  { views: readonly TPath[]; multiple?: boolean; description?: string }
>;

Each repeated instance has a stable, non-empty key unique within its view, a metadata object, and schema-validated data. See Write app UI for the implementation.

Frequently asked questions

Use views to adapt an instance to page context and metadata to describe its placement or label.

Do I need multiple instances to change UI between pages?

No. Views let one instance change with the current context. Enable multiple when you need distinct tiles, pages, or other entries from the same app.

Does metadata have a fixed format?

It’s an object with the fields you agree to use, such as label, icon, or position. Your UI decides what those fields mean.

Getting Started

App Capabilities

Writing apps

Define where apps render

Define slots

Describe the space

Allow multiple slot instances

Context chooses the view

SDK reference

Frequently asked questions

​Define slots

​Describe the space

​Allow multiple slot instances

​Context chooses the view

​SDK reference

​Frequently asked questions

Define slots

Describe the space

Allow multiple slot instances

Context chooses the view

SDK reference

Frequently asked questions