UI & Custom Events

These events handle UI slot rendering, quick buy modals, and custom event patterns.

ui:slot:set

Dispatched by app to setup the content of a ui slot.

note

For simpler component rendering, you can also use the nube.render() and nube.clearSlot() methods. See Script Structure for more information.

Example

import type { NubeSDK } from "@tiendanube/nube-sdk-types";
import { Row, Txt } from "@tiendanube/nube-sdk-jsx";

function MyComponent() {
  return (
    <Row>
      <Txt>Hello!</Txt>
    </Row>
  );
}

export function App(nube: NubeSDK) {
  nube.send("ui:slot:set", () => ({
    ui: {
      slots: {
        after_line_items: <MyComponent />,
      },
    },
  }));
}

It can also be used to remove the content of a slot, by specifying undefined as the content.

Example

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  nube.send("ui:slot:set", () => ({
    ui: {
      slots: {
        before_line_items: undefined,
      },
    },
  }));
}

quickbuy:open

Storefront only. Dispatched by store when a quick buy modal is opened for a product.

eventPayload

This event includes state.eventPayload with the full product data for the product associated with the quick buy modal. Key properties include:

Property	Type	Description
id	number	Unique identifier for the product.
name	object	Localized product name (e.g. { es: "...", pt: "..." }).
description	object	Localized product description.
handle	object	Localized product URL handle.
brand	string or null	Product brand name.
canonical_url	string	Product canonical URL.
images	array	Product images (each with src, alt, width, height).
variants	array	Product variants (each with id, price, stock, values, etc.).
published	boolean	Whether the product is published.
free_shipping	boolean	Whether the product qualifies for free shipping.
requires_shipping	boolean	Whether the product requires shipping.
tags	string	Product tags.
created_at	string	ISO 8601 creation timestamp.
updated_at	string	ISO 8601 last update timestamp.

The full type is Record<string, unknown>, so additional properties may be present.

Example

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  nube.on("quickbuy:open", ({ eventPayload }) => {
    console.log(`Quick buy opened for product: ${eventPayload?.id}`);
    console.log("Variants:", eventPayload?.variants);
  });
}

quickbuy:close

Storefront only. Dispatched by store when a quick buy modal is closed.

eventPayload

This event includes state.eventPayload with the same product data as quickbuy:open .

Example

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  nube.on("quickbuy:close", ({ eventPayload }) => {
    console.log(`Quick buy closed for product: ${eventPayload?.id}`);
  });
}

product:variant_selected

Storefront only. Dispatched by store on the product detail page when the customer picks a variant. Only emitted for products that have more than one variant — single-variant PDPs do not fire it.

eventPayload

This event includes state.eventPayload with data describing the selected variant. The shape mirrors ProductVariant , with the most relevant fields being:

Property	Type	Description
id	number	Unique identifier for the selected variant.
product_id	number	Identifier of the parent product.
price	string | null	Current selling price. When the variant is on promotion, this is the promotional price; otherwise the regular price.
compare_at_price	string | null	Original price before any discount.
promotional_price	string | null	Promotional price when the variant is on sale, otherwise null.
stock	number | null	Total available stock for the variant.
stock_management	boolean	Whether stock tracking is enabled for this variant.
inventory_levels	array	Stock entries per location (each with id, variant_id, location_id, stock).
sku	string | null	SKU identifier.
image_id	number | null	ID of the variant's associated image.
values	LocalizedString[]	The option values that identify the variant (e.g. size and color), localized in pt, es, and en.
customData.color	string | undefined	Convenience field with the first option value when the product is configured with a color attribute.

The full type is Record<string, unknown>, so additional ProductVariant fields may also be present.

Example

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  nube.on("product:variant_selected", ({ eventPayload, location }) => {
    const variant = eventPayload;
    const productId = location.page.type === "product"
      ? location.page.data.product.id
      : null;

    console.log(`Variant ${variant?.id} selected on product ${productId}`);
    console.log("Price:", variant?.price);
    console.log("Stock:", variant?.stock);
  });
}

Custom events

Custom events follow the pattern custom:<namespace>:<action>. They can be both listened to and sent (when the platform supports it). For example, when content is rendered in the modal_content slot, the SDK dispatches custom:modal:close when the user closes the modal.

Example

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  nube.on("custom:modal:close", (state) => {
    // Handle cleanup or state updates when the modal is closed
  });
}

Use the same pattern for other custom namespaces (e.g. custom:drawer:close). The listener always receives (state, event) where event is the full event name string.

• Learn more about Browser APIs
• Learn more about Components
• Learn more about UI Slots