Client Context allows Embeddable users to pass different values to their Embeddable workspaces programmatically. The scope of these variables and their use is entirely up to you!

We’ve found that two of our most-requested uses for Client Context are:

We’re going to show you how you might go about handling that in your application on this page.

Important Note: Client Context is only available in components, not in your data models. It is meant to include front-facing values that are exposed on the website, so make sure not to pass any secure information with it. To do that, you’d want to use Security context instead.

To pass client context values to your Embeddable, you can add them to the web component like this:

/* All of these values could also be variables you define in your code */
return <Embeddable
    clientContext={{
      currency: 'dollar',
      currencySymbol: '$',
      flag: '🇺🇸',
      language: 'English',
      name: 'United States',
    }}
  />

Note: you’re not limited to strings. You can pass numbers, booleans, arrays or objects as properties.

However, before you start passing values to live Embeddables you’d probably like to do some testing first. The best way to do this is to edit src/embeddable.com/presets/client-contexts.cc.yml like this:

- name: United States
  clientContext:
    currency: 'dollar'
    currencySymbol: '$'
    flag: '🇺🇸'
    language: 'English'
    name: 'United States'

- name: France
  clientContext:
    currency: 'euro'
    currencySymbol: '€'
    flag: '🇫🇷'
    language: 'français'
    name: 'France'

This will create two contexts (United States and France) from which you can select in the dropdown at the top of your workspace, like this:

image.png

Once you’re able to switch between contexts, you’ll want to do something with them. Let’s go ahead and create a very simple component to display some of our data. Client Context can be passed in as props to any Embeddable component, so accessing it is super easy. Let’s first create a DisplayContext.emb.ts file, like this:

// src/components/displaycontext/DisplayContext.emb.ts
import { EmbeddedComponentMeta, defineComponent } from '@embeddable.com/react';

import Component from './index';
import { Inputs } from '@embeddable.com/react';

export const meta = {
  name: 'DisplayContext',
  label: 'Display Context',
  defaultHeight: 400,
  defaultWidth: 400,
  inputs: [
    {
      name: 'title',
      type: 'string',
      label: 'Title',
      description: 'The title for the component',
    },
    {
      name: 'description',
      type: 'string',
      label: 'Description',
      description: 'The description inside the component',
    },
  ],
} as const satisfies EmbeddedComponentMeta;

export default defineComponent(Component, meta, {
  props: (inputs: Inputs<typeof meta>, _, clientContext) => {
    return {
      title: inputs.title,
      body: inputs.description,
      clientContext,
    };
  },
});

As you can see, we’re passing clientContext as a prop within the defineComponent function. This will allow us to access client context values in our JSX components. You’ll probably note that this file is importing index.tsx which doesn’t currently exist. Let’s rectify that by creating this file:

// src/components/displaycontext/index.ts
import React from 'react';

type Props = {
  title: string;
  description: string;
  clientContext: {
    currency: string;
    currencySymbol: string;
    flag: string;
    language: string;
    name: string;
  };
};

export default (props: Props) => {
  const { title, description, clientContext } = props;
  const { currency, currencySymbol, flag, language, name } = clientContext;
  return (
    <div>
      <h1>{title}</h1>
      <p>
        <em>{description}</em>
      </p>
      <ul>
        <li>
          Country: {name} {flag}
        </li>
        <li>Language: {language} </li>
        <li>Currency: {currency}</li>
        <li>Currency Symbol: {currencySymbol}</li>
      </ul>
    </div>
  );
};

When we add this component to our dev environment, we can see the values change as we switch client contexts, like this:

image.png