Add renderMode object to PickupLocationItemApi

[james-a-c]

Background

Part of https://github.com/shop/issues-checkout/issues/9641
Closes https://github.com/shop/issues-checkout/issues/10513

Changes to the Delivery section through the delivery redesign experiment have created 2 locations for the pickup-location-option-item-render-after target to render extensions, one of them being in a modal. We need a way to inform the extensions that are being rendered in this target that they are currently in a modal (or not).

implementation in checkout-web can be found in this draft PR stack

Screenshots

Inline

In modal

Solution

Extend the same pattern we use for shipping-option-item-render-after by exposing the renderMode object on PickupLocationItemApi

Create a new shared RenderMode type to be used in shipping-option-item + pickup-location-item

Update shipping-option-item to use the new shared type.

// shared.ts
export interface RenderMode {
  overlay: boolean;
}

PickupLocationItemApi
{
  isTargetSelected: ...
  target: ...
  renderMode: RenderMode
}

ShippingOptionItemApi
{
  isTargetSelected: ...
  target: ...
  renderMode: RenderMode
}

🎩

• Create or using an existing checkout UI extension. (docs for generating an extension)
• Update the @shopify/ui-extensions package within your extension with the npm snapshot and run npm install

"@shopify/ui-extensions": "0.0.0-snapshot-20260113163731" 

• Import the usePickupLocationOptionTarget hook into your extension
• Ensure that the overlay property is available

import { usePickupLocationOptionTarget } from "@shopify/ui-extensions/checkout/preact";

const renderingInModal = pickupLocationOptionTarget.renderMode.overlay; 

Checklist

• I have 🎩'd these changes
• I have updated relevant documentation

[james-a-c]

• Add renderMode object to PickupLocationItemApi #3674 👈 (View in Graphite)
• 2026-01-rc

This stack of pull requests is managed by Graphite. Learn more about stacking.

[james-a-c]

/snapit

[dnagoda]

/snapit

[dnagoda]

/snapit

[james-a-c]

/snapit

[james-a-c]

/snapit

[james-a-c]

/snapit

[shopify-github-actions-access]

🫰✨ Thanks @james-a-c! Your snapshot has been published to npm.

Test the snapshot by updating your package.json with the newly published version:

"@shopify/ui-extensions": "0.0.0-snapshot-20260113163731"

[lrsterrett]

👋 We should change the base branch to be 2026-01-rc (unless you also need this feature available in 2025-10, but based on the threads I went through I don't think this is the case). 2026-01-rc is the branch we'll promote to 2026-01

[lrsterrett]

I'm thinking we could add a type called something generic like RenderMode in packages/ui-extensions/src/surfaces/checkout/api/shared.ts as I'd imagine that the type used in ShippingOptionItemRenderMode will remain consistent and won't accidentally diverge in the future if not intended to.

[james-a-c]

Agreed. A shared type makes sense here to avoid the duplication. I will update

[lrsterrett]

Oh and also, we're trying to get away from the duplication, but the current flow for making changes to checkout ui extension types/docs is to add them to the equivalent directory in checkout-web under ./packages/ui-extensions as well. Checkout-web still references that 'private package' internally for the latest 'unstable/rc' api version. 🙃 Sorry for the hassle, happy to help if you need it!

[james-a-c]

👋 We should change the base branch to be 2026-01-rc (unless you also need this feature available in 2025-10, but based on the threads I went through I don't think this is the case). 2026-01-rc is the branch we'll promote to 2026-01

Just updated to base branch to 2026-01-rc

And no problem on making the shared type change in checkout-web as well!

[james-a-c]

@lrsterrett ready for another review! 🙂

[james-a-c]

/snapit

[james-a-c]

/snapit