Using the Render API

The REST API is a way to fetch generated html for a specific component.

Note: The render API renders your designs on Plasmic’s servers, not from your application, so it doesn’t have access to your custom code components.

The REST API can be called from the following route. https://codegen.plasmic.app/api/v1/loader/html/MODE/PROJECTID/COMPONENTNAME

Argument	Description
`MODE`	Mode should be either `published` or `preview`. If set to published it’s going to be fetched the latest published version of your project, in preview mode, the current state of your project is used to generate the html.
`PROJECTID`	This is the id of the project where the component that you want to fetch is present, you can find the id of your project by accessing it in the studio, and copying it from the url.
`COMPONENTNAME`	This should be the name of the component that you want to fetch, you should use the same name that you used in the studio.

Authentication

The REST API can only be requested if you have authorization to access the requested project. In the request for the endpoint you should include x-plasmic-api-project-token in the headers. The field has to be set in the following way.

Copy

{
  "x-plasmic-api-project-tokens": "PROJECTID:PROJECTTOKEN"
}

Where PROJECTID is the id of the project that you are request, and PROJECTTOKEN is a token that will indicate if you are authorized to perform the request, you can find the token for your project in: https://studio.plasmic.app/projects/[PROJECTID]/docs/loader#showToken=true

Hydration

Since event listeners aren’t going to be attached when only the API result is used, you may have to perform hydration, this way your pages will become responsive to user interaction. You can indicate it with the following query params.

/api/v1/loader/html/MODE/PROJECTID/COMPONENTNAME&hydrate=1&embedHydrate=1

Argument	Default	Description
`hydrate`	`0`	This option indicates if the API response should include a hydration script that will perform hydration in the response. Without the hydration process event listeners aren’t going to be attached, which can lead to malfunctioning of the page. For example, Plume components are going to be unresponsive in regards to user interaction, if the hydration process is not executed.
`embedHydrate`	`0`	The embedHydrate option defines if the data to be hydrated should be embedded in the response of the API or if should be dynamically fetched during the hydration step. When embedHydrate=0 there is a faster initial html paint, but there is a slower hydration process. When embedHydrate=1, the hydration process is going to be faster, but the initial html paint is going to be slower.

We recomend always using hydrate=1, since only requiring the hydration process without embedHydrate won’t cause any harm to the page even you don’t need it.

Customization

You can achieve customization of the component by providing componentProps and globalVariants as query params to the API endpoint.

/api/v1/loader/html/MODE/PROJECTID/COMPONENTNAME&componentProps={}&globalVariants=[]

Argument	Description
`componentProps`	This should be the props to be passed to the component, with this you can customize which variants are going to be active, define the value of expected props and override slots content (with text only). This field is expected to be a stringified object.
`globalVariants`	If you need to define which global variant should be active for this component, you have to specify it with this field, it’s expected to be a stringified array having a description of each global variant to be activated. The following example describes it.

Prepass

When you have components that fetch content to be displayed (such as a CMS), the API is not configured to fetch this content by default, so it must be fetched on the client-side. However, you can specify that this content should be prefetched in the server and provided in the HTML response. It is important to note that the HTML response from the server is cached. Therefore, any change in the content that was fetched will not be visible until the cache expires. You can bypass this by publishing a new version or using maxAge as a query parameter.

Argument	Default	Description
`prepass`	`0`	This option allows you to prefetch content on the server, use `prepass=1` to enable it or `prepass=0` to disable it.
`maxAge`	`3600`	This option indicates how long the content returned by the server will be cached (i.e. 3600 represents 60 minutes). A high value is recommended as a low value can reduce the performance of your application. This argument is only valid if `prepass=1`.

Examples

The following are Javascript snippets that show how the api can be used.

Copy

const response = await fetch(
  'https://codegen.plasmic.app/api/v1/loader/html/preview/PROJECTID/COMPONENTNAME?hydrate=1&embedHydrate=1',
  {
    headers: {
      // Your project ID and public API token
      'x-plasmic-api-project-tokens': 'PROJECTID:APITOKEN'
      // You can find your PROJECT token by visiting
      // https://studio.plasmic.app/projects/[PROJECTID]/docs/loader#showToken=true
    }
  }
);
const result = await response.json();
document.body.innerHTML = result.html;

// If you want hydration to happen, load and call the hydrater
if (window.__plasmicHydrater) {
  window.__plasmicHydrater.hydrateAll();
} else {
  var script = document.createElement('script');
  script.src = 'https://codegen.plasmic.app/static/js/loader-hydrate.js';
  document.body.appendChild(script);
}

The REST API lets you customize both component props and global variants that should be passed down for the requested component.

Copy

const query = new URLSearchParams([
  ['hydrate', '1'],
  ['embedHydrate', '1'],
  [
    'componentProps',
    JSON.stringify({
      // Your component props
    })
  ],
  [
    'globalVariants',
    JSON.stringify([
      // Your global variants
      {
        name: 'Theme',
        value: 'Dark'
      }
    ])
  ]
]);

const response = await fetch(
  `https://codegen.plasmic.app/api/v1/loader/html/preview/PROJECTID/COMPONENTNAME?${query}`,
  {
    headers: {
      // Your project ID and public API token
      'x-plasmic-api-project-tokens': 'PROJECTID:APITOKEN'
      // You can find your PROJECT token by visiting
      // https://studio.plasmic.app/projects/[PROJECTID]/docs/loader#showToken=true
    }
  }
);
const result = await response.json();
document.body.innerHTML = result.html;

// If you want hydration to happen, load and call the hydrater
if (window.__plasmicHydrater) {
  window.__plasmicHydrater.hydrateAll();
} else {
  var script = document.createElement('script');
  script.src = 'https://codegen.plasmic.app/static/js/loader-hydrate.js';
  document.body.appendChild(script);
}

Was this page helpful?

Have feedback on this page? Let us know on our forum.