---
title: "CustomElementRegistry | JavaScript maps SDK"
description: "Documentation for MapTiler SDK"
---

> For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL.

# Interface CustomElementRegistry

The **`CustomElementRegistry`** interface provides methods for registering custom elements and querying registered elements. To get an instance of it, use the window.customElements property.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry)

interface CustomElementRegistry {  
    [define](#define-1)(  
        name: string,  
        constructor: [CustomElementConstructor](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.CustomElementConstructor/),  
        options?: [ElementDefinitionOptions](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.ElementDefinitionOptions/),  
    ): void;  
    [get](#get-1)(name: string): [CustomElementConstructor](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.CustomElementConstructor/) | undefined;  
    [getName](#getname-1)(constructor: [CustomElementConstructor](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.CustomElementConstructor/)): string | null;  
    [initialize](#initialize-1)(root: [Node](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.Node/)): void;  
    [upgrade](#upgrade-1)(root: [Node](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.Node/)): void;  
    [whenDefined](#whendefined-1)(name: string): Promise<[CustomElementConstructor](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.CustomElementConstructor/)\>;  
}

##### Index

### Methods[](#methods)

[define](#define) [get](#get) [getName](#getname) [initialize](#initialize) [upgrade](#upgrade) [whenDefined](#whendefined)

## Methods[](#methods-1)

### define[](#define)

-   define(  
        name: string,  
        constructor: [CustomElementConstructor](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.CustomElementConstructor/),  
        options?: [ElementDefinitionOptions](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.ElementDefinitionOptions/),  
    ): void[](#define-1)
    
    The **`define()`** method of the CustomElementRegistry interface adds a definition for a custom element to the custom element registry, mapping its name to the constructor which will be used to create it.
    
    [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/define)
    
    #### Parameters
    
    -   name: string
    -   constructor: [CustomElementConstructor](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.CustomElementConstructor/)
    -   `Optional`options: [ElementDefinitionOptions](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.ElementDefinitionOptions/)
    
    #### Returns void
    

### get[](#get)

-   get(name: string): [CustomElementConstructor](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.CustomElementConstructor/) | undefined[](#get-1)
    
    The **`get()`** method of the CustomElementRegistry interface returns the constructor for a previously-defined custom element.
    
    [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/get)
    
    #### Parameters
    
    -   name: string
    
    #### Returns [CustomElementConstructor](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.CustomElementConstructor/) | undefined
    

### getName[](#getname)

-   getName(constructor: [CustomElementConstructor](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.CustomElementConstructor/)): string | null[](#getname-1)
    
    The **`getName()`** method of the CustomElementRegistry interface returns the name for a previously-defined custom element.
    
    [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/getName)
    
    #### Parameters
    
    -   constructor: [CustomElementConstructor](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.CustomElementConstructor/)
    
    #### Returns string | null
    

### initialize[](#initialize)

-   initialize(root: [Node](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.Node/)): void[](#initialize-1)
    
    #### Parameters
    
    -   root: [Node](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.Node/)
    
    #### Returns void
    

### upgrade[](#upgrade)

-   upgrade(root: [Node](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.Node/)): void[](#upgrade-1)
    
    The **`upgrade()`** method of the CustomElementRegistry interface upgrades all shadow-containing custom elements in a Node subtree, even before they are connected to the main document.
    
    [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/upgrade)
    
    #### Parameters
    
    -   root: [Node](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.Node/)
    
    #### Returns void
    

### whenDefined[](#whendefined)

-   whenDefined(name: string): Promise<[CustomElementConstructor](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.CustomElementConstructor/)\>[](#whendefined-1)
    
    The **`whenDefined()`** method of the CustomElementRegistry interface returns a Promise that resolves when the named element is defined.
    
    [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/whenDefined)
    
    #### Parameters
    
    -   name: string
    
    #### Returns Promise<[CustomElementConstructor](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.CustomElementConstructor/)\>