Add UI
To add pages, navigation, tabs, and cards to the dashboard, add UI to a graft. A graft’s UI is an island: a bundle with its own copy of Svelte. Orchard loads the bundle and gives it an empty element to draw in. Because the island does not share Orchard’s build, a graft can use any library.
Define what the graft adds
Section titled “Define what the graft adds”ui/src/client.ts default-exports what the graft adds:
import { mount, unmount } from 'svelte';import { defineGraft } from '@orchardlabs/graft-sdk/client';import Notes from './Notes.svelte';import NotesCard from './NotesCard.svelte';
export default defineGraft({ slots: { 'nav.primary': [{ id: 'notes', label: 'Notes', href: '/notes' }], 'project.overview.cards': [ { id: 'recent', mount: (target, props, host) => { const app = mount(NotesCard, { target, props: { ...props, host } }); return () => unmount(app); } } ] }, screens: { home: (target, props, host) => { const app = mount(Notes, { target, props: { host } }); return () => unmount(app); } }});For each place a graft can add to, refer to the slot reference.
Add a screen
Section titled “Add a screen”List each screen in graft.json under ui.screens, with its path and layout:
| Layout | Behavior |
|---|---|
shell |
Draws inside Orchard’s sidebar and header. |
fullscreen |
Takes the whole window. |
A screen at /admin/<graft id>, or below it, renders in the Instance admin area, and only superadmins reach it. Pair it with an admin.nav entry. Orchard ignores a screen under /admin/ that uses another path.
Use the host object
Section titled “Use the host object”Each mount function receives host, the graft’s interface to Orchard’s UI.
| Member | Description |
|---|---|
host.graft |
The graft’s id, version, apiBase, and assetBase. |
host.api(path, init?) |
Returns JSON from the graft’s API. Paths are relative to /apiv1/<graft-id>. json in init sends a body. |
host.fetch(path, init?) |
Returns the raw response. |
host.stores.user, .org, .theme, .route |
Svelte-compatible stores. Use $user in a component. |
host.navigate(href, options?) |
Navigates on the client. |
host.toast(message, tone?, options?) |
Shows one of Orchard’s toasts. |
host.confirm({ title, body, confirmLabel, danger }) |
Shows Orchard’s confirmation dialog, and resolves to a boolean. |
host.onOrgEvent(handler) |
Receives live events for the current organization. |
host.refreshSlots() |
Evaluates the visible functions of the graft’s slot items again. |
Match Orchard’s styles
Section titled “Match Orchard’s styles”@orchardlabs/graft-ui is Orchard’s component kit, packaged for grafts. It includes components such as Button, SectionCard, Field, Input, Select, Modal, and EmptyState.
Orchard sets theme colors, fonts, and spacing as CSS variables on the page. You can use var(--text-muted) and var(--bg-surface) in a graft’s own styles.
A graft bundles its copy of the kit. A graft built against an older Orchard keeps that version’s components until you rebuild it. Colors and fonts follow the instance.
Errors
Section titled “Errors”Orchard wraps each mount. If a graft throws while mounting or updating, that element shows an error with a Retry button. The rest of the page keeps working.
Related resources
Section titled “Related resources”- graft.json - Declare screens and their layouts.
- Write server code - Add the API routes that
host.apicalls.