Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: Add a sidebar widget
sidebarTitle: Sidebar widget
description: Add an info card to a built-in detail page's sidebar — pulling its own data, gated by permissions, with loading and empty states.
---
The product, order, and customer detail pages each render a `<Slot>` in their right-hand sidebar — typically named `<resource>.form_sidebar`. Widgets rendered into these slots see the current record and can fetch their own data without disturbing the host page.
This recipe builds a "Loyalty status" card for the customer detail page: read-only, fetches the customer's points + tier, shows a spinner while loading, an empty state when there's no data, and hides itself for staff without the right permission.
## The component
```tsx
// src/slots/loyalty-status-card.tsx
import { useQuery } from '@tanstack/react-query'
import {
adminClient,
Badge,
Card,
CardContent,
CardHeader,
CardTitle,
Empty,
EmptyDescription,
Skeleton,
usePermissions,
useStore,
} from '@spree/dashboard'
import { Trophy } from 'lucide-react'
interface LoyaltyRecord {
customer_id: string
points: number
tier: 'bronze' | 'silver' | 'gold'
}
interface Props {
// The customer detail page's slot context — see the slots catalog.
customer: { id: string }
}
export function LoyaltyStatusCard({ customer }: Props) {
const { storeId } = useStore()
const { permissions } = usePermissions()
const canRead = permissions.can('read', 'loyalty_record')
const { data, isLoading } = useQuery({
queryKey: ['loyalty', storeId, customer.id],
queryFn: () =>
adminClient.request<{ data: LoyaltyRecord | null }>(
'GET',
`/customers/${customer.id}/loyalty`,
),
staleTime: 30_000,
enabled: canRead,
})
// Hide entirely for staff without the permission — same behavior as
// core's permission-gated cards.
if (!canRead) return null
return (
<Card>
<CardHeader>
<CardTitle className="flex items-center gap-2">
<Trophy className="size-4" />
Loyalty status
</CardTitle>
</CardHeader>
<CardContent>
{isLoading ? (
<Skeleton className="h-8 w-32" />
) : !data?.data ? (
<Empty>
<EmptyDescription>No loyalty record</EmptyDescription>
</Empty>
) : (
<div className="space-y-2">
<Badge variant={tierVariant(data.data.tier)}>{data.data.tier}</Badge>
<p className="text-sm text-muted-foreground">{data.data.points} points</p>
</div>
)}
</CardContent>
</Card>
)
}
function tierVariant(tier: LoyaltyRecord['tier']) {
return tier === 'gold' ? 'default' : 'secondary'
}
```
Worth noting:
- **`storeId` in the query key.** The dashboard is multi-store; without this, switching stores leaves stale data on screen.
- **`staleTime: 30_000`** keeps the data fresh enough for a sidebar widget without re-fetching on every focus event.
- **Three states.** Loading (`<Skeleton>`), empty (`<Empty>`), and loaded. Skipping the empty state ships a card that says "0 points" when really the customer has never been enrolled — different meaning, different UX.
- **Strings are hardcoded for brevity.** Real widgets should go through i18n — see [Translations](/developer/dashboard/customization/translations).
## Register the widget
```ts
// src/plugins.ts (in your dashboard app)
import { defineDashboardPlugin } from '@spree/dashboard'
import { LoyaltyStatusCard } from './slots/loyalty-status-card'
defineDashboardPlugin({
slots: {
'customer.form_sidebar': [{
id: 'loyalty-status',
component: LoyaltyStatusCard as never,
position: 50,
}],
},
})
```
The permission gate lives *inside* the component (`usePermissions`) rather than in an `if` predicate on the entry — the predicate only receives the slot context today, not ambient permissions (see the [slots catalog](/developer/dashboard/slots-catalog#ambient-context)).
`position: 50` puts the card near the top of the sidebar (built-in cards typically use 100/200/300). Pick a number based on whether your widget is more or less important than the others — for a "status" card, near the top is right.
## When to fetch in the widget vs. read from the host
The pattern above fetches its own data. The alternative is to read it from the resource the host passes:
```tsx
function MyCard({ customer }: { customer: Customer }) {
return <div>{customer.loyalty_points}</div> // host already loaded it
}
```
Choose based on **whether the data is hot path for the rest of the page**:
| Data | Approach |
|---|---|
| Already on the host's serializer (e.g., `customer.tags`) | Read from the slot context — no extra HTTP |
| Conditional, expensive, or owned by your plugin | Fetch in the widget |
| Sometimes-needed (e.g., gated by feature flag) | Fetch in the widget |
A widget that always fetches is wasteful when the host already has the data. A widget that reads from the host but the host doesn't serialize is broken. Match the pattern to the source of truth.
## Loading states for the host page
The built-in detail pages render their sidebar only after the record has loaded, so the context record is always set when your widget mounts. If you register into a slot where that's not guaranteed (check the slots catalog entry), guard defensively:
```tsx
if (!customer) return null // or a <Skeleton> to reserve layout space
```
## Reference
- [Slots catalog → form sidebars](/developer/dashboard/slots-catalog) — every page-level sidebar slot
- [`useQuery`](https://tanstack.com/query/v5/docs/framework/react/reference/useQuery) — query key conventions
- [`@spree/dashboard` README](https://github.com/spree/spree/blob/main/packages/dashboard/README.md) — the multi-store model and why `storeId` belongs in the key