> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embeddables.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices: Passing data into/out of Embeddables to be prefilled

> URL params? Embed code? Window functions? Etc...

## Use-cases

Some common use-cases that we often see:

1. I want to prefill data like email addresses into my Embeddable that users have already entered previously on my site.
2. I want to prefill data from my Embeddable into an embedded component inside it, like a Calendly booker or Stripe component.
3. I want to pass data like email addresses out of my Embeddable to be used on a subsequent page on my website.

<Info>
  This doc is for passing data to be immediately prefilled somewhere in front of the user.

  For ways of sending/receiving the data to/from an external source like an API, database or SaaS app, check out [Guides: Deciding how best to send/receive data](/guides/how-best-to-send-data)
</Info>

## Passing data into an Embeddable to prefill fields (e.g. email address)

### Method 1: URL params

<Steps>
  <Step title="Add the fields into the URL as params">
    * For example: `https://mywebsite.com/onboarding?email=ada@lovelace.com`.
    * Make sure that this is the URL when the Embeddable first loads,
      since that's when it will look for URL params.
  </Step>

  <Step title="Set those fields to be URL-controlled">
    * Head to the Embeddable-wide settings
    * Go to the More tab
    * Add the fields to the URL Keys block,
      separated by newlines.
  </Step>
</Steps>

### Method 2: Embed code keys/attributes

<Steps>
  <Step title="Add each field as an attribute on the <savvy> HTML element">
    * For example: `<savvy id="flow_abc" email="ada@lovelace.com"></savvy>`.
    * Make sure that these attributes are present when the element is first added
      to the DOM, since that's when it will look for URL params.
  </Step>

  <Step title="Set those fields to be Embed Code-controlled">
    * Head to the Embeddable-wide settings
    * Go to the More tab
    * Add the fields to the Embed Code Keys block,
      separated by newlines.
  </Step>
</Steps>

### Method 3: Custom code using Window variable

<Note>
  This works best when you want to prefill data immediately (as soon as the
  Embeddable loads).
</Note>

<Steps>
  <Step title="Place the data on a Window variable in your website/webapp">
    * From within your website or webapp, create a variable
      in the Window scope with a unique name.
    * Add the data you want to prefill into that variable.
    * **Make sure to that this happens before the Embeddable loads.**

    ```javascript Your Website/Webapp Code theme={null}
    window.myEmbeddablesPrefillData = {
      email: 'ada@lovelace.com'
    }
    ```
  </Step>

  <Step title="Add a custom code Action, triggered on first load">
    For more info on how to do this, check out:

    <Card title="How To: Run custom code when the Embeddable loads" href="/how-to/run-custom-code-on-load" icon="book-open">
      Setting up a custom code Action that executes when the Embeddable first loads.
    </Card>
  </Step>

  <Step title="Grab the data from the Window variable, and then set the User Data">
    * Pull out the data from the Window variable that you
      set up in Step 1.
    * Then use `helperFunctions.setUserData()` to set the
      User Data based on the payload sent with that event:

    ```javascript Custom Code Action - Triggered on First Load theme={null}
    function output(userData, helperFunctions) {
      const dataToPrefill = window.myEmbeddablesPrefillData
        if (dataToPrefill) {
          helperFunctions.setUserData(dataToPrefill);
        }
      });
    }
    ```
  </Step>
</Steps>

### Method 4: Custom code using custom Window event

<Note>
  This works best when you want to prefill data after the Embeddable has already
  loaded
</Note>

<Steps>
  <Step title="Add a custom code Action, triggered on first load">
    For more info on how to do this, check out:

    <Card title="How To: Run custom code when the Embeddable loads" href="/how-to/run-custom-code-on-load" icon="book-open">
      Setting up a custom code Action that executes when the Embeddable first loads.
    </Card>
  </Step>

  <Step title="Listen for a custom Window event, and then set the User Data">
    * Use `window.addEventListener()` to listen for a
      custom event that you will define.
    * Then use `helperFunctions.setUserData()` to set the
      User Data based on the payload sent with that event:

    ```javascript Custom Code Action - Triggered on First Load theme={null}
    function output(userData, helperFunctions) {
      window.addEventListener('embeddables:my_custom_prefill_event', (event) => {
        const detail = event.detail || {};
        const dataToPrefill = detail.prefill_data
        if (dataToPrefill) {
          helperFunctions.setUserData(dataToPrefill);
        }
      });
    }
    ```
  </Step>

  <Step title="Send the custom Window event from your website/webapp">
    * From your website or webapp, create a new
      Custom Event with the prefill data, and
      send it to the Window:

    ```javascript Your Website/Webapp Code theme={null}
    const myEvent = new CustomEvent('embeddables:my_custom_prefill_event', {
      detail: {
        prefill_data: {
          email: 'ada@lovelace.com'
        }
      }
    })
    window.dispatchEvent(myEvent);
    ```
  </Step>
</Steps>

<Note>
  This page is unfinished and is queued up to be completed soon - watch this
  space!
</Note>