How to Embed the ImageLayer Widget in Your App

An embedded generation workflow needs more than a visual component. The host application must issue scoped end-user sessions, keep secret credentials on a trusted server, handle product events, and respect current workspace entitlements.

What you’re building

By the end of this guide, your app will render the ImageLayer widget and attach the authentication properties required by an enabled workspace. Available modes, content types, models, and quotes come from the server configuration.

The browser element is one Web Component; live end-user generation also requires backend session-token issuance and admitted billing or entitlement state.

Step 1: Get your API key

Create an account and workspace, then open API Keys in the dashboard. Registration does not include a promise of generation credits. A request can run only when the workspace has an admitted entitlement and the current billing mode allows it.

Create a publishable widget key and copy it for the browser configuration. Keep secret keys on your server.

For an end-user app, your backend must create a short-lived session token with POST /v1/auth/session. The widget uses that token to scope generation history, quota, and analytics to the current user.

Step 2: Add the widget

Vanilla HTML

The simplest integration. Add the script tag and the widget element:

<script type="module" src="https://cdn.imagelayer.app/widget/latest/image-layer.js"></script>

<image-layer id="imagelayer-widget" api-url="https://api.imagelayer.app" />
<script>
  const widget = document.getElementById('imagelayer-widget');
  widget.apiKey = 'il_pub_your_publishable_key_here';
  widget.sessionToken = 'SESSION_TOKEN_FROM_YOUR_SERVER';
</script>

That’s the client-side embed. The <image-layer> element is a Web Component, so no framework wrapper is required. Mint every end-user session token on your server and never expose a secret API key in browser code.

React

Web Components work in React without a wrapper. Import the package and use the tag directly:

import '@imagelayer/widget';

function ImageGenerator({ sessionToken }) {
  return (
    <image-layer
      ref={(el) => {
        if (el) {
          el.apiKey = 'il_pub_your_publishable_key_here';
          el.sessionToken = sessionToken;
        }
      }}
      api-url="https://api.imagelayer.app"
    />
  );
}

If you’re using TypeScript, React will warn about the unknown element. Add a type declaration:

declare namespace JSX {
  interface IntrinsicElements {
    'image-layer': React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement> & {
        apiKey?: string;
        'api-url': string;
        sessionToken?: string;
      },
      HTMLElement
    >;
  }
}

Vue

Vue handles Web Components natively. Use the tag in any .vue file:

<template>
  <image-layer ref="widget" api-url="https://api.imagelayer.app" />
</template>

<script setup>
import '@imagelayer/widget';
import { onMounted, ref } from 'vue';

const widget = ref(null);
onMounted(() => {
  widget.value.apiKey = 'il_pub_your_publishable_key_here';
  widget.value.sessionToken = 'SESSION_TOKEN_FROM_YOUR_SERVER';
});
</script>

Tell Vue’s compiler to treat image-layer as a custom element in your vite.config.ts:

vue({
  template: {
    compilerOptions: {
      isCustomElement: (tag) => tag === 'image-layer',
    },
  },
});

npm install (optional)

If you prefer bundling the widget with your app instead of loading from CDN:

npm install @imagelayer/widget

Then import it anywhere in your app. The custom element registers itself on import.

Step 3: Set up your brand kit

Go to Dashboard > Settings and configure your brand:

• Logo: upload your logo for overlays
• Colors: set your brand palette so generated images use your colors
• AI brand guidelines: describe your visual style, tone, and elements to avoid

Saved brand context can steer supported model requests toward your palette, tone, and avoid list. It does not guarantee an exact match. Use approved source files and deterministic overlays when a logo or legal line must be exact.

Step 4: Test it

Open your app with the widget embedded and inspect a LinkedIn-post setup:

1. Select “Blog Promo” as the content type
2. Choose “LinkedIn Post” as the platform preset
3. Type a description of what you need
4. Review the selected model and quoted credits; submit only if the authenticated workspace is admitted

If generation is admitted, inspect the returned dimensions, crop, text, and brand direction. A platform preset requests a format; generated output still needs review. Users can add approved logo overlays in the branding editor where the workspace enables that control.

What your users see

The widget walks users through a four-step flow:

1. Input — pick a content type, choose a platform, describe the image
2. Generate — the server validates the request, quote, entitlement, and model admission before provider work
3. Brand — add logo, adjust layout, fine-tune the composition
4. Download — export an approved result

Content type templates replace part of an open-ended prompt with named fields. They do not remove the need to review the result.

Beyond the basics

Depending on the current workspace plan and server configuration, you can enable:

• Sketch-to-image mode — users supply a rough layout as guidance, then review the generated draft (Starter plan)
• Reference images — upload a reference photo for the AI to use as a starting point (Starter plan)
• Custom content type templates — create templates specific to your use case
• Usage analytics — track who generates what and how many credits are used

If you are choosing an implementation path, use the framework integration guides for React, Vue, Next.js, Angular, Svelte, and Astro. If you want to wire the server contract first, start with the API reference. The use case library contains product-planning scenarios, not customer case studies.

Next steps

Create a workspace and follow the integration guide for your framework. Account creation lets you configure the workspace; generation remains subject to the current entitlement and billing controls.

If you have questions, check the widget documentation, compare framework-specific setup guides, or contact us.