# SDK API Reference The configurator web component is a custom HTML element. Just as regular elements, it provides HTML attributes and methods, which are described in the following. ## Attributes
NameTypeDescriptionDefault
parametersstring

Initial list of parameters formatted as query parameters, e.g, param(<input-identifier>)=<input-type>(<input-value>). Example:

"param(123)=material(123)&param(987)=number(10)"

undefined
show-uibooleanShow or hide the action menu UI layer.true
template-uuidstringThe id (UUID) of the template to load. Mutually exclusive with the organization-uuid/article-id pair (if both are supplied, template-uuid takes precedence).undefined
organization-uuidstringThe id (UUID) of the organization used together with article-id to resolve a template by its article identifier. Required when article-id is provided and template-uuid is omitted.undefined
article-idstringThe optional article identifier used (together with organization-uuid) to load a template without knowing its template UUID. If both template-uuid and article-id are present, the component uses template-uuid.undefined
use-external-menubooleanSet to true if a separate menu is being provided.false
pixel-rationumberOverride the device pixel ratio used for rendering to trade off image sharpness versus performance. Higher values increase clarity at additional GPU cost.undefined
## Methods ### captureSnapshotInMemory The asynchronous `captureSnapshotInMemory()` method of the `Configurator` interface creates an image from the rendering and resolves the returned `Promise` with the data URL string that contains the image data. Optional arguments allow choosing the output mime type and quality. Throws an error if the Canvas 2d context is not available. #### Signature ```typescript async captureSnapshotInMemory(mimeType?: "image/png" | "image/jpeg", quality?: number): Promise ``` #### Parameters `mimeType` The optional image type. Can be `"image/png"` or `"image/jpeg"`. Defaults to `"image/jpeg"`. `quality` Optional numeric quality for the JPEG encoder between 0 and 1. Defaults to `0.95`. Ignored for `"image/png"`. #### Return value Returns a `Promise` which resolves with the data URL `string` ### downloadPdf The asynchronous `downloadPdf()` method of the `Configurator` interface generates a PDF document of the current configuration and starts a file download. An optional [`PdfDownloadOptions`](#pdfdownloadoptions) object can be passed to customise the PDF title and provide custom table data (headers, rows, column widths, and a total row). When called without options (or with `options.table` omitted), the PDF table is populated from the internal pricing service. When `options.table` is provided, the caller-supplied data is rendered instead. #### Signature ```typescript async downloadPdf(options?: PdfDownloadOptions): Promise ``` #### Parameters `options` An optional [`PdfDownloadOptions`](#pdfdownloadoptions) object. #### Return value Returns a `Promise` which resolves to `undefined`. #### Example ```javascript const configurator = document.querySelector('cm-configurator-main'); configurator.addEventListener('loadingCompleted', async () => { await configurator.downloadPdf({ title: 'YOUR CUSTOM PRODUCT', table: { headers: ['DESCRIPTION', 'CODE', 'PRICE'], rows: [ ['Acme Deluxe Cabinet - Oak', 'ACME-DLX-001', '€ 1,200'], ['Acme Granite Worktop 800mm', 'ACME-GRN-800', '€ 450'], ], columnWidthPercentages: [45, 30, 25], total: { label: 'Total Price', value: '€ 1,650' }, }, }); }); ``` ### generateQrCode The asynchronous `generateQrCode()` method of the `Configurator` interface creates an QR code image for the provided `url` and resolves the returned `Promise` with the data URL string that contains the image data. The QR code image can be configured by setting the `errorCorrectionLevel` to `'high'` or `'low'` and by setting the `width` or `margin` `number` parameter. #### Signature ```typescript async generateQrCode(url: string, errorCorrectionLevel: "high" | "low", width: number, margin: number): Promise ``` #### Parameters `url` The url `string` the QR code should represent. `errorCorrectionLevel` The correction level that should be applied to the QR code generation. Can be `'high'` or `'low'`. `width` The `number` of the resulting image width in pixels. `margin` The `number` of the margin around the QR code in pixels. #### Return value Returns a `Promise` which resolves with the data URL `string` ### getParameterList The `getParameterList()` method of the `Configurator` interface returns a list of the available [`ConfiguratorParameters`](#configuratorparameters) once the configurator is loaded (after the [`configurationLoaded`](#configurationloaded) event was fired). #### Signature ```typescript getParameterList(): ConfiguratorParameters[] ``` #### Parameters *None* #### Return value Returns an `Array` of `Object` conforming to the [`ConfiguratorParameters`](#configuratorparameters) type. ### getPricesAsList The asynchronous `getPricesAsList()` method of the `Configurator` interface fetches a list of item price data, if configured on the platform. The `Promise` resolves with an array of [`PricedItem`](#priceditem). #### Signature ```typescript async getPricesAsList(): Promise ``` #### Parameters *None* #### Return value Returns a `Promise` which resolves with an `Array` of `Object` conforming to the [`PricedItem`](#priceditem) type. ### loadConfigurator The asynchronous `loadConfigurator()` method of the `Configurator` interface loads the template for the supplied template UUID and starts rendering. #### Signature ```typescript async loadConfigurator(templatedUuid: string): Promise ``` #### Parameters `templateUuid` The id `string` of the template to load. #### Return value Returns a `Promise` which resolves to `undefined`. ### loadConfiguratorByArticleId The asynchronous `loadConfiguratorByArticleId()` method of the `Configurator` interface resolves a template via an organization UUID / article ID pair and then loads it. Use this when you only know a business-level article identifier within an organization instead of a specific template UUID. #### Signature ```typescript loadConfiguratorByArticleId(organizationUuid: string, articleId: string): void ``` #### Parameters `organizationUuid` The organization id `string` the article identifier belongs to. `articleId` The article identifier `string` unique within the organization. #### Return value Returns a `Promise` which resolves to `undefined`. ### resetCamera The `resetCamera()` method of the `Configurator` interface resets the camera angle and zoom level of the visualisation. #### Signature ```typescript resetCamera(): void ``` #### Parameters *None* #### Return value Returns `undefined`. ### saveSnapshot The `saveSnapshot()` method of the `Configurator` interface creates an image from the rendering and starts a file download. Optional arguments allow choosing the output mime type and quality. #### Signature ```typescript saveSnapshot(mimeType?: "image/png" | "image/jpeg", quality?: number): void ``` #### Parameters `mimeType` The optional image type. Can be `"image/png"` or `"image/jpeg"`. Defaults to `"image/jpeg"`. `quality` Optional numeric quality for the JPEG encoder between 0 and 1. Defaults to `0.95`. Ignored for `"image/png"`. #### Return value Returns `undefined`. ### setParameter The asynchronous `setParameter()` method of the `Configurator` interface sets a parameter for the current template and starts rendering. There is advanced guide on [how to set parameters](/dev/configurator/web-components/setting-parameters.md). #### Signature ```typescript async setParameter(id: string, type: ConfigType, value: number | string | ImageDataParameter | ColorOverlayParameter): Promise ``` #### Parameters `id` The parameter identifier `string`. `type` The parameter [`ConfigTyp`](#configtype) `value` The parameter value as `number` , `string` or `ImageDataParameter`. #### Return value Returns a `Promise` which resolves to `undefined`. ### toggleDimensionGuides The `toggleDimensionGuides()` method of the `Configurator` interface shows or hides dimension guides, if guides are configured for the template. #### Signature ```typescript toggleDimensionGuides(): void ``` #### Parameters *None* #### Return value Returns `undefined`. ### toggleFullscreen The `toggleFullscreen()` method of the `Configurator` interface requests fullscreen view for the configurator and exits fullscreen respectively. #### Signature ```typescript toggleFullscreen(): void ``` #### Parameters *None* #### Return value Returns `undefined`. ### viewInAr The asynchronous `viewInAr()` method of the `Configurator` interface fetches the AR model for the current configuration and opens the native AR view on iOS or Android. For other devices it will generate and display a QR code, which links to the AR view. #### Signature ```typescript async viewInAr(): Promise ``` #### Parameters *None* #### Return value Returns a `Promise` which resolves to `undefined`. ### zoomIn The `zoomIn()` method of the `Configurator` interface increases the zoom. It accepts a value between 0 and 1, where larger values produce larger zoom steps. #### Signature ```typescript zoomIn(value: number): void ``` #### Parameters `value` The zoom percentage as a `number` between 0 and 1. #### Return value Returns `undefined`. ### zoomOut The `zoomOut()` method of the `Configurator` interface decreases the zoom. It accepts a value between 0 and 1, where larger values produce larger zoom steps. #### Signature ```typescript zoomOut(value: number): void ``` #### Parameters `value` The zoom percentage as a `number` between 0 and 1. #### Return value Returns `undefined`. ## Events ### arUrl The `arUrl` event fires when the AR model for the current configuration is ready. The URL `string` to open the AR viewer can be accessed via `event.detail`. #### Syntax ```typescript addEventListener("arUrl", (event: { detail: string }) => {}): void ``` ### changeCompleted The `changeCompleted` event fires after a parameter was changed using [`setParameter`](#setparameter) and the visualization change is done. The `event.detail` object contains the changed parameter `id` . #### Syntax ```typescript addEventListener("changeCompleted", (event: { id: string}) => {}): void ``` ### configurationLoaded The `configurationLoaded` event fires after the configurator finished loading the configuration. It will fire for the initial configuration and on subsequent changes triggered through the menu UI, changes to attributes, calls to [`loadConfigurator`](#loadconfigurator) or [`setParameter`](#setparameter). #### Syntax ```typescript addEventListener("configurationLoaded", (event) => {}): void ``` ### loadingCompleted The `loadingCompleted` event fires after the configurator finished loading the template. It will fire for the initial configuration and if the template is changed via the [`template-uuid`](#properties) attribute or a call to [`loadConfigurator`](#loadconfigurator). #### Syntax ```typescript addEventListener("loadingCompleted", (event) => {}): void ``` ## Types ### ConfigType ```typescript type ConfigType = "config" | "material" | "material-article-id" | "template" | "image" | "string" | "boolean" | "number" | "object" | "int" | "float" ``` ### ConfiguratorParameters ```typescript type ConfiguratorParameters = { id: string type: ConfigType name: string values: { id: string name: string }[] value?: unknown } ``` ### PricedItem ```typescript type PricedItem = { description: string sku?: string price: number currency: "EUR" | "USD" | "GBP" amount: number } ``` ### ImageDataParameter ```typescript type ImageDataParameter = { contentType: "image/jpeg" | "image/png" data: Uint8Array } ``` ### ColorOverlayParameter ```typescript type ColorOverlayParameter = { materialId: string size: [number, number] overlay: | string | { data: Uint8Array contentType: string } } ``` ### PdfDownloadOptions ```typescript type PdfDownloadOptions = { /** Custom title for the PDF. Overrides the default title from the template settings. */ title?: string /** Table configuration. If omitted, the internal pricing service data is used. */ table?: { /** Column headers (e.g., ["DESCRIPTION", "CODE", "PRICE"]) */ headers: string[] /** Data rows; each row is an array of strings matching the headers */ rows: string[][] /** Optional column width percentages. If omitted, columns are distributed equally. */ columnWidthPercentages?: number[] /** Optional total row rendered in bold at the bottom of the table */ total?: { label: string value: string } } } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.colormass.com/dev/configurator/web-components/sdk-api-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.