Surfaces allow you to insert custom content into designated areas of the extension UI. This guide walks you through creating and registering a new surface.

Determine the target slot

Identify which target slot this surface should occupy. Valid options are:

slot.header — appears at the top of the extension area
slot.content — main content area
slot.footer — bottom of the extension area
slot.footer-links — footer link row

Create the surface file

Create a new file in packages/extension/src/surfaces/ named after the slot (e.g., Header.tsx, Content.tsx, Footer.tsx).

Use this template:

import { Surface, useCapabilities, useContextData } from '@stackable-labs/sdk-extension-react'
import { ui } from '@stackable-labs/sdk-extension-react'

export const [SurfaceName] = () => {
  return (
    <Surface id="[target]">
      {/* Surface content here */}
    </Surface>
  )
}

If the surface requires state management, import and use the existing store from ../store.

Register the surface in index.tsx

Import the new surface component and add it to the createExtension factory function alongside existing surfaces.

Update manifest.json

Add the target to the targets array in packages/extension/public/manifest.json. Also add any required permissions based on the target-permission mapping:

slot.header → context:read
slot.content → context:read, data:query, actions:toast, actions:invoke, messaging:send
slot.footer → (none)
slot.footer-links → (none)

Only add permissions that aren't already declared.

Verify

Confirm the surface renders by checking the import chain: index.tsx → Surface component → Surface id matches manifest target
Confirm manifest.json is valid JSON with no duplicate targets or permissions