Getting started with Sampler

Creating a Sampler Image API requires a Sampler Account and an account with Figma. You can create an account with Figma here and with us here.

You're able to connect the two accounts by integrating with Figma from the Integrations section of Sampler dashboard.

Creating a Sampler Template

Creating a Template for your image API can be done from our dashboard here. It can be linked to any Figma Design File you want. You can find a great starting point here in our boilerplate example, which can be copied to your own account in Figma and adjusted however you like.

Adding dynamic content to your Figma files

There is a couple of specific naming conventions you can use in Figma to tell Sampler what to do.

Frames

Sampler looks through your Figma file looking for a Frame layer starting with a '#'. Only everything inside this layer is shown in the image rendered by Sampler. You can tell Sampler which frame to render by passing the query parameter frame: ?frame=name_of_the_frame.

Dynamic text content

When adding a layer of Text in Figma, you can use double curly brackets to declare a variable (e.g.: {{ text }} for a variable named "text"). This variable can then be changed dynamically through the API when rendering the image. This can done in the layer name as well as inlined as part of the Text layer's content.

💡 Protip: The inlined variables can be used to only replace some parts of the Text layer content, while keeping the rest intact. For example in "Hello {{target}}!", only the {{target}} part is changeable. You may even use multiple variables in the same Text layer with different styling as well.

Dynamic images

The same syntax is used on images in Figma, where naming the image layer {{ image_url }} enables you to change your image asset inside your template. If no image is provided it falls back to the image set in Figma.

Dynamic background colors

When using the double curly brackets syntax on a Shape layer in Figma the variable is used the change the background color of that Layer.

Calling the Sampler API with query parameters

Each template has a unique URL, that can be enhanced using the variables you declared in Figma as query parameters. The format can be changed by changing the file format in the URL to either .jpeg to .png or .pdf.

Calling our boilerplate template without query parameters returns the following image:

https://sampler.app/api/ae56cd06-c1e7-44df-b03d-471267075f22/image.jpeg

Adding the query parameters below gives us the following image:

?headline=Dynamic%20text%20%F0%9F%91%8D

It's important to encode the data before sending it as a query parameter. Here's an example of how it could be done in TypeScript:

function Sampler(templateId: string) {
  const SAMPLER_BASE_URL = 'https://sampler.app/api'

  const getImage = (data: Record<string, string>) => {
    const searchParams = new URLSearchParams(data).toString()
    const query = searchParams ? `?${searchParams}` : ''
    return `${SAMPLER_BASE_URL}/${templateId}/image.jpeg${query}`
  }

  return {
    getImage,
  }
}

const pricingTemplate = Sampler(PRICING_TEMPLATE_ID)

const openGraphImage = pricingTemplate.getImage({
  title: 'Custom Dynamic data',
  price: '29',
})

Use case for Open Graph Images

If you're using Sampler to create Open Graph Images for your site, the output from the code above can be inserted into meta tags on each page. The following example in in JSX:

<meta property="og:image" content="{openGraphImage}" />
<meta name="twitter:image" content="{openGraphImage}" />
<meta name="twitter:card" content="summary_large_image" />
<meta property="og:image:height" content="630" />
<meta property="og:image:width" content="1200" />

If you need anything don't hesitate to reach out at rasmus@sampler.app 👋