---
title: listener
description: >-
  The listener feature is a lightweight, headless observer that detects
  returning Shop users from an email input.
source_url:
  html: 'https://shopify.dev/docs/api/shop-sdk/reference/listener'
  md: 'https://shopify.dev/docs/api/shop-sdk/reference/listener.md'
api_name: shop-sdk
---

# listener

The `listener` feature is a lightweight, headless observer that monitors an email input for returning [Shop](https://shop.app) users. It renders no UI — it only watches and reports — making it ideal for custom flows where the merchant controls the entire visual experience.

***

## Usage

Create a listener instance via the SDK:

```javascript
const sdk = window.ShopSDK.initialize({
  apiKey: 'YOUR_CLIENT_ID',
});


const listener = await sdk.create('listener', {
  inputElement: document.querySelector('#email'),
  onMatched() {
    console.log('Returning Shop user detected!');
  },
});
```

You can also eagerly preload the feature loader before calling `create`:

```javascript
const sdk = window.ShopSDK.initialize({
  apiKey: 'YOUR_CLIENT_ID',
  features: { listener: true },
});
```

#### ListenerConfig

Config accepted by `sdk.create('listener', config)`.

The `listener` feature is a lightweight, headless observer that monitors an email input for returning Shop users. It renders no UI — it only watches and reports — making it ideal for custom flows where the merchant controls the entire visual experience.

* **input​Element**

  **HTMLElement**

  The DOM element to observe for email input.

* **input​Selector**

  **string**

  CSS selector for the email input on the page (alternative to `inputElement`).

* **on​Matched**

  **() => void**

  Fired when a returning Shop user is detected for the entered email.

* **on​Ready**

  **(event: ReadyEvent) => void**

  SDK-level ready handler (fires when the element's loader resolves).

### ReadyEvent

Event payload passed to the \`onReady\` handler when a feature element finishes loading.

* detail

  Underlying \`CustomEvent.detail\` from the element's \`'loaded'\` event, when available. Shape is feature-specific — e.g. for lead-capture this includes fields like \`userFound\`, \`loginTitle\`, etc. emitted by \`useAuthorizeEventListener\`.

  ```ts
  unknown
  ```

* elementTagName

  Tag name of the element that became ready, e.g. \`shop-lead-capture\`.

  ```ts
  string
  ```

#### ListenerInstance

Runtime instance returned by `sdk.create('listener')`.

The listener is headless — `element` is always `null` and the SDK appends the underlying element to `document.body` automatically. Exposes `onReady`, `onMatched`, and `destroy`.

* **destroy**

  **() => void**

  **required**

  Tear down listeners and remove the element from the DOM if attached.

* **element**

  **null**

  **required**

  Always `null` — the listener is headless and manages its own DOM.

* **on​Matched**

  **(handler: () => void) => void**

  **required**

  Register an `onMatched` handler. Fires whenever a returning Shop user is detected.

* **on​Ready**

  **(handler: (event: ReadyEvent) => void) => void**

  **required**

  Register an `onReady` handler. Fires immediately if already ready.

### Examples

* #### Basic usage

  ##### Description

  Observe an email input by passing a DOM element and react when a returning Shop user is detected.

  ##### HTML

  ```html
  <script type="module" src="https://cdn.shopify.com/shopifycloud/shop-js/modules/v2/loader.sdk.esm.js"></script>

  <input id="email" type="email" placeholder="Enter your email" />

  <script type="module">
    const sdk = window.ShopSDK.initialize({
      apiKey: 'YOUR_CLIENT_ID',
    });

    const listener = await sdk.create('listener', {
      inputElement: document.querySelector('#email'),
      onMatched() {
        console.log('Returning Shop user detected!');
      },
    });
  </script>
  ```

* #### Selector-based

  ##### Description

  Observe an email input by passing a CSS selector instead of a DOM element.

  ##### HTML

  ```html
  <script type="module" src="https://cdn.shopify.com/shopifycloud/shop-js/modules/v2/loader.sdk.esm.js"></script>

  <input id="newsletter-email" type="email" placeholder="Enter your email" />

  <script type="module">
    const sdk = window.ShopSDK.initialize({
      apiKey: 'YOUR_CLIENT_ID',
    });

    const listener = await sdk.create('listener', {
      inputSelector: '#newsletter-email',
      onMatched() {
        console.log('Returning Shop user detected!');
      },
    });
  </script>
  ```

***

## Related

[Overview - Shop SDK](https://shopify.dev/docs/api/shop-sdk/reference/shop-sdk)

***