Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Frontend Modules

Wix Design System (WDS)

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

import { Property, PropertyList, ExpandableSection, RequestResponseExamples } from "@wix/docs-ui/content";

{/* Generated by @wix/tw-typedoc-to-wix-docs from packages/site-service-lightbox/src/definition/index.ts. Do not edit this file directly — edit the TSDoc in the source package. */}

# Lightbox Functions

## close()

Closes the open popup.

It closes whichever popup is open, regardless of the component that calls it.

Site visitors can also close a popup themselves, with its close button, the Escape key, or by
going to another page.

### Method Declaration

```ts
close(): void
```

### Examples

<RequestResponseExamples defaultName="close" requestName="JavaScript" requestType="JavaScript" examples={[
  {
    title: `Close the popup from a button inside it`,
    content: {
      methodExample: {
        Request: `~~~tsx
import { useService } from '@wix/services-manager-react'
import { LightboxDefinition } from '@wix/site-service-lightbox/definition'

function QuickViewCloseButton() {
    const lightboxService = useService(LightboxDefinition)

    return (
        <button aria-label="Close quick view" onClick={() => lightboxService.close()}>
            Close
        </button>
    )
}
~~~`
      }
    }
  },
  {
    title: `Close a popup after 10 seconds`,
    content: {
      methodExample: {
        Request: `~~~tsx
import { useEffect } from 'react'
import { useService } from '@wix/services-manager-react'
import { LightboxDefinition } from '@wix/site-service-lightbox/definition'

function ShippingPromo() {
    const lightboxService = useService(LightboxDefinition)

    useEffect(() => {
        const timer = setTimeout(() => lightboxService.close(), 10000)

        // Clear the timer if the component unmounts first.
        return () => clearTimeout(timer)
    }, [lightboxService])

    return <p>Free shipping on all orders this week.</p>
}
~~~`
      }
    }
  }
]} />

---

## getContext()

> **Deprecated.** Use `getPayload()` instead.

Retrieves the payload of the open popup.

### Method Declaration

```ts
getContext<TPayload = unknown>(): TPayload
```

### Returns

<PropertyList bordered>
  <Property name="Return Type:" type="TPayload" />
</PropertyList>

### Examples

<RequestResponseExamples defaultName="getContext" requestName="JavaScript" requestType="JavaScript" examples={[
  {
    title: `Call getContext`,
    content: {
      methodExample: {
        Request: `~~~ts
const result = lightboxService.getContext()
~~~`
      }
    }
  }
]} />

---

## getPayload()

Retrieves the payload of the open popup.

It returns the payload of whichever popup is open, regardless of the component that calls it, so call
it from a component inside the popup.

It takes no arguments. In TypeScript, you can specify the payload's type in angle brackets, as in
`getPayload<QuickViewPayload | undefined>()`. Use the type you specified for `payload` in `open()`,
plus `undefined`. TypeScript doesn't check that the two match, so a different type gives you wrong
types without an error. Without a type, the return type is `unknown`.

### Method Declaration

```ts
getPayload<TPayload = unknown>(): TPayload
```

### Returns

<PropertyList bordered>
  <Property name="Return Type:" type="TPayload">
    Payload of the open popup.

    `undefined` when no popup is open.
  </Property>
</PropertyList>

### Examples

<RequestResponseExamples defaultName="getPayload" requestName="JavaScript" requestType="JavaScript" examples={[
  {
    title: `Show the product a quick view popup was opened with`,
    content: {
      methodExample: {
        Request: `~~~tsx
import { useService } from '@wix/services-manager-react'
import { LightboxDefinition } from '@wix/site-service-lightbox/definition'

type QuickViewPayload = { productId: string }

function QuickViewDetails() {
    const lightboxService = useService(LightboxDefinition)
    const payload = lightboxService.getPayload<QuickViewPayload | undefined>()

    if (!payload) {
        return <p>Choose a product to see its details.</p>
    }

    return <ProductSummary productId={payload.productId} />
}
~~~`
      }
    }
  }
]} />

---

## open()

Opens a popup over the current page.

Opening a popup closes any popup that's already open. If the popup is already open, it stays open,
and its payload is replaced with the `payload` you specify, or with `undefined` if you omit
`payload`.

Specify the popup by `slug`. Specifying it by `pageId` is deprecated, but still works.

### Method Declaration

```ts
open<TPayload = unknown>(options: LightboxOpenOptions<TPayload>): Promise<void>
```

### Method Parameters

<PropertyList bordered>
  <Property name="options" type="LightboxOpenOptions<TPayload>" required>
    Options for opening the popup.
    <ExpandableSection name="LightboxOpenBySlugOptions Properties">
      <PropertyList>
        <Property name="context" type="TPayload" deprecated>
          Information to pass to the popup. Ignored when you specify `payload`.
        </Property>
        <Property name="pageId" type="never" />
        <Property name="payload" type="TPayload">
          Information to pass to the popup. Components inside the popup read it with `getPayload()`.
        </Property>
        <Property name="slug" type="string" required>
          Slug of the popup to open, the `pageUriSEO` of the popup page. It's the popup's `slug` in
          `@wix/site-service-pages`.
        </Property>
      </PropertyList>
    </ExpandableSection>
    <ExpandableSection name="LightboxOpenByPageIdOptions Properties">
      <PropertyList>
        <Property name="context" type="TPayload" deprecated>
          Information to pass to the popup. Ignored when you specify `payload`.
        </Property>
        <Property name="pageId" type="string" required deprecated>
          Page ID of the popup to open.

          This is the popup's key in the `pages` map of `@wix/site-service-pages`. The page's `popup` property
          must be `true`.

          It isn't the page's `appPageId`.
        </Property>
        <Property name="payload" type="TPayload">
          Information to pass to the popup. Components inside the popup read it with `getPayload()`.
        </Property>
        <Property name="slug" type="never" />
      </PropertyList>
    </ExpandableSection>
  </Property>
</PropertyList>

### Returns

<PropertyList bordered>
  <Property name="Return Type:" type="Promise<void>">
    Promise that resolves with no value once the popup is open. It rejects when the popup
    can't be opened, for example when no popup has the `slug` you specify.
  </Property>
</PropertyList>

### Examples

<RequestResponseExamples defaultName="open" requestName="JavaScript" requestType="JavaScript" examples={[
  {
    title: `Open a quick view popup from a button`,
    content: {
      methodExample: {
        Request: `~~~tsx
import { useState } from 'react'
import { useService } from '@wix/services-manager-react'
import { LightboxDefinition } from '@wix/site-service-lightbox/definition'

type QuickViewPayload = { productId: string }

function QuickViewButton({ productId }: { productId: string }) {
    const lightboxService = useService(LightboxDefinition)
    const [failed, setFailed] = useState(false)

    const openQuickView = () => {
        setFailed(false)
        lightboxService
            .open<QuickViewPayload>({ slug: 'quick-view', payload: { productId } })
            .catch(() => setFailed(true))
    }

    return (
        <>
            <button onClick={openQuickView}>Quick view</button>
            {failed && <p>Quick view isn't available right now.</p>}
        </>
    )
}
~~~`
      }
    }
  }
]} />