How to Add an Action Button

Add a small piece of UI to a built-in panel screen without copying it. The order detail page is a panel screen you don’t own. To add a button, a badge, or a note to it, you drop a widget at one of its zones. The SDK renders your component there, and the rest of the page keeps working exactly as shipped. This tutorial adds a Copy link button to the order summary section that copies a link to the order.

A widget is additive, not a replacement. It layers your component onto a built-in page at a documented zone. Reach for it first whenever you just want to add something to an existing screen.

Add the button

Create the widget file

Drop a file under src/widgets/. Export the component as the default and a config built with defineWidgetConfig. Target orders.detail.summary.after. Your component renders in the order summary section footer and receives the loaded order as data.

apps/vendor/src/widgets/order-copy-link.tsx

import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
import type { HttpTypes } from "@medusajs/types"
import { Button, Container, toast } from "@medusajs/ui"

export const config = defineWidgetConfig({
  zone: "orders.detail.summary.after",
})

const OrderCopyLink = ({ data: order }: { data?: HttpTypes.AdminOrder }) => {
  if (!order) return null

  const orderLink = `${window.location.origin}/orders/${order.id}`

  const handleCopy = async () => {
    try {
      await navigator.clipboard.writeText(orderLink)
      toast.success("Link copied")
    } catch {
      toast.error("Couldn't copy the link")
    }
  }

  return (
    <Container className="flex items-center justify-end p-3">
      <Button size="small" variant="secondary" onClick={handleCopy}>
        Copy link
      </Button>
    </Container>
  )
}

export default OrderCopyLink

Read the zone id

A zone id is <domain>.<view>.<slot>.<placement>. The last segment is the placement.

Placement	Effect
`before`	Renders before the built-in content of the zone
`after`	Renders after the built-in content

Multiple before or after widgets on the same zone stack in registration order.

Reload the panel

Start the project and open any order in the vendor portal. Widget files hot-reload. The Copy link button appears in the summary section footer, and the rest of the page is untouched.

Terminal

bun run dev

Order detail zones

These zones are mounted on the vendor order detail page.

Zone	Where it renders
`orders.detail.summary.before` / `.after`	Inside the order summary section (around its footer)
`orders.detail.main.before` / `.after`	Around the main column (summary, payment, fulfillment)
`orders.detail.side.before` / `.after`	Around the sidebar (customer, activity)

Each zone is passed the loaded order as data. The full, valid set is typed as WidgetZoneId and generated from the panel’s own zone hosts. Let your editor autocomplete zone: to see every option.

A zone that no page renders can’t be targeted and won’t type-check. Set zone: "not.a.zone" and tsc (bun run lint) fails with a “not assignable to WidgetZoneId” error.

Verify

Confirm the widget works end to end.

Open an order. The Copy link button renders in the summary section footer.
Click it. The link is copied and a toast appears.
Change the zone to orders.detail.side.before and reload. The button moves to the top of the sidebar.
Set zone: "not.a.zone". tsc (bun run lint) fails with a “not assignable to WidgetZoneId” error.
Delete the file. The button disappears, and nothing else changed.

FAQ

What can I read from the order?

The zone passes the loaded order as data (HttpTypes.AdminOrder): id, display id, totals, items, payment_collections, customer, and more. Build the link (or any UI) from it.

Can a block ship this instead of the host app?

Yes. Put the same file in a block’s vendor_ui entry under src/widgets/. Installing the block adds the button with no wiring.

Can I render more than a button?

The zone renders any React component, such as a badge, an action menu, or a whole section. You have the full order in data.

How-Tos

Integrations

Deployment

Add the button

Order detail zones

Verify

FAQ

Next steps

Add a widget

Extend forms and tables

​Add the button

​Order detail zones

​Verify

​FAQ

​Next steps

Add a widget

Extend forms and tables

Add the button

Order detail zones

Verify

FAQ

Next steps