custom-elements.json

A file format for describing custom elements

Type object
File match custom-elements.json
Schema URL https://catalog.lintel.tools/schemas/schemastore/custom-elements-json/latest.json
Source https://raw.githubusercontent.com/webcomponents/custom-elements-manifest/main/schema.json

Validate with Lintel

npx @lintel/lintel check
Type: object

The top-level interface of a custom elements manifest file.

Because custom elements are JavaScript classes, describing a custom element may require describing arbitrary JavaScript concepts like modules, classes, functions, etc. So custom elements manifests are capable of documenting the elements in a package, as well as those JavaScript concepts.

The modules described in a package should be the public entrypoints that other packages may import from. Multiple modules may export the same object via re-exports, but in most cases a package should document the single canonical export that should be used.

Properties

modules JavaScriptModule[] required

An array of the modules this package contains.

schemaVersion string required

The version of the schema used in this file.

deprecated string | boolean

Whether the package is deprecated. If the value is a string, it's the reason for the deprecation.

readme string

The Markdown to use for the main readme of this package.

This can be used to override the readme used by Github or npm if that file contains information irrelevant to custom element catalogs and documentation viewers.

Definitions

Attribute object
name string required
default string

The default value of the attribute, if any.

As attributes are always strings, this is the actual value, not a human readable description.

deprecated string | boolean

Whether the attribute is deprecated. If the value is a string, it's the reason for the deprecation.

description string

A markdown description.

fieldName string

The name of the field this attribute is associated with, if any.

inheritedFrom object

A reference to an export of a module.

All references are required to be publically accessible, so the canonical representation of a reference is the export it's available from.

package should generally refer to an npm package name. If package is undefined then the reference is local to this package. If module is undefined the reference is local to the containing module.

References to global symbols like Array, HTMLElement, or Event should use a package name of "global:".

3 nested properties
name string required
module string
package string
summary string

A markdown summary suitable for display in a listing.

type object
3 nested properties
text string required

The full string representation of the type, in whatever type syntax is used, such as JSDoc, Closure, or TypeScript.

references TypeReference[]

An array of references to the types in the type string.

These references have optional indices into the type string so that tools can understand the references in the type string independently of the type system and syntax. For example, a documentation viewer could display the type Array<FooElement | BarElement> with cross-references to FooElement and BarElement without understanding arrays, generics, or union types.

source object

A reference to the source of a declaration or member.

1 nested properties
href string required

An absolute URL to the source (ie. a GitHub URL).

ClassDeclaration object
kind string required
Values: "class"
name string required
deprecated string | boolean

Whether the class or mixin is deprecated. If the value is a string, it's the reason for the deprecation.

description string

A markdown description of the class.

members ClassField | ClassMethod[]
mixins Reference[]

Any class mixins applied in the extends clause of this class.

If mixins are applied in the class definition, then the true superclass of this class is the result of applying mixins in order to the superclass.

Mixins must be listed in order of their application to the superclass or previous mixin application. This means that the innermost mixin is listed first. This may read backwards from the common order in JavaScript, but matches the order of language used to describe mixin application, like "S with A, B".

source object

A reference to the source of a declaration or member.

1 nested properties
href string required

An absolute URL to the source (ie. a GitHub URL).

summary string

A markdown summary suitable for display in a listing.

superclass object

A reference to an export of a module.

All references are required to be publically accessible, so the canonical representation of a reference is the export it's available from.

package should generally refer to an npm package name. If package is undefined then the reference is local to this package. If module is undefined the reference is local to the containing module.

References to global symbols like Array, HTMLElement, or Event should use a package name of "global:".

3 nested properties
name string required
module string
package string
ClassField object
kind string required
Values: "field"
name string required
default string
deprecated string | boolean

Whether the property is deprecated. If the value is a string, it's the reason for the deprecation.

description string

A markdown description of the field.

inheritedFrom object

A reference to an export of a module.

All references are required to be publically accessible, so the canonical representation of a reference is the export it's available from.

package should generally refer to an npm package name. If package is undefined then the reference is local to this package. If module is undefined the reference is local to the containing module.

References to global symbols like Array, HTMLElement, or Event should use a package name of "global:".

3 nested properties
name string required
module string
package string
privacy string
Values: "private" "protected" "public"
readonly boolean

Whether the property is read-only.

source object

A reference to the source of a declaration or member.

1 nested properties
href string required

An absolute URL to the source (ie. a GitHub URL).

static boolean
summary string

A markdown summary suitable for display in a listing.

type object
3 nested properties
text string required

The full string representation of the type, in whatever type syntax is used, such as JSDoc, Closure, or TypeScript.

references TypeReference[]

An array of references to the types in the type string.

These references have optional indices into the type string so that tools can understand the references in the type string independently of the type system and syntax. For example, a documentation viewer could display the type Array<FooElement | BarElement> with cross-references to FooElement and BarElement without understanding arrays, generics, or union types.

source object

A reference to the source of a declaration or member.

1 nested properties
href string required

An absolute URL to the source (ie. a GitHub URL).

ClassMethod object
kind string required
Values: "method"
name string required
deprecated string | boolean

Whether the function is deprecated. If the value is a string, it's the reason for the deprecation.

description string

A markdown description.

inheritedFrom object

A reference to an export of a module.

All references are required to be publically accessible, so the canonical representation of a reference is the export it's available from.

package should generally refer to an npm package name. If package is undefined then the reference is local to this package. If module is undefined the reference is local to the containing module.

References to global symbols like Array, HTMLElement, or Event should use a package name of "global:".

3 nested properties
name string required
module string
package string
parameters Parameter[]
privacy string
Values: "private" "protected" "public"
return object
3 nested properties
description string

A markdown description.

summary string

A markdown summary suitable for display in a listing.

type object
3 nested properties
text string required

The full string representation of the type, in whatever type syntax is used, such as JSDoc, Closure, or TypeScript.

references TypeReference[]

An array of references to the types in the type string.

These references have optional indices into the type string so that tools can understand the references in the type string independently of the type system and syntax. For example, a documentation viewer could display the type Array<FooElement | BarElement> with cross-references to FooElement and BarElement without understanding arrays, generics, or union types.

source object

A reference to the source of a declaration or member.

source object

A reference to the source of a declaration or member.

1 nested properties
href string required

An absolute URL to the source (ie. a GitHub URL).

static boolean
summary string

A markdown summary suitable for display in a listing.

CssCustomProperty object
name string required

The name of the property, including leading --.

default string
deprecated string | boolean

Whether the CSS custom property is deprecated. If the value is a string, it's the reason for the deprecation.

description string

A markdown description.

summary string

A markdown summary suitable for display in a listing.

syntax string

The expected syntax of the defined property. Defaults to "*".

The syntax must be a valid CSS syntax string as defined in the CSS Properties and Values API.

Examples:

"": accepts a color " | ": accepts lengths or percentages but not calc expressions with a combination of the two "small | medium | large": accepts one of these values set as custom idents. "*": any valid token

CssCustomState object

The description of a CSS Custom State https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet

name string required

The name of the state. Note: Unlike CSS custom properties, custom states do not have a leading --.

deprecated string | boolean

Whether the CSS custom state is deprecated. If the value is a string, it's the reason for the deprecation.

description string

A markdown description.

summary string

A markdown summary suitable for display in a listing.

CssPart object

The description of a CSS Part

name string required
deprecated string | boolean

Whether the CSS shadow part is deprecated. If the value is a string, it's the reason for the deprecation.

description string

A markdown description.

summary string

A markdown summary suitable for display in a listing.

CustomElementDeclaration object

A description of a custom element class.

Custom elements are JavaScript classes, so this extends from ClassDeclaration and adds custom-element-specific features like attributes, events, and slots.

Note that tagName in this interface is optional. Tag names are not neccessarily part of a custom element class, but belong to the definition (often called the "registration") or the customElements.define() call.

Because classes and tag names can only be registered once, there's a one-to-one relationship between classes and tag names. For ease of use, we allow the tag name here.

Some packages define and register custom elements in separate modules. In these cases one Module should contain the CustomElement without a tagName, and another Module should contain the CustomElementExport.

customElement boolean required

Distinguishes a regular JavaScript class from a custom element class

Values: true
kind string required
Values: "class"
name string required
attributes Attribute[]

The attributes that this element is known to understand.

cssParts CssPart[]
cssProperties CssCustomProperty[]
cssStates CssCustomState[]
demos Demo[]
deprecated string | boolean

Whether the class or mixin is deprecated. If the value is a string, it's the reason for the deprecation.

description string

A markdown description of the class.

events Event[]

The events that this element fires.

members ClassField | ClassMethod[]
mixins Reference[]

Any class mixins applied in the extends clause of this class.

If mixins are applied in the class definition, then the true superclass of this class is the result of applying mixins in order to the superclass.

Mixins must be listed in order of their application to the superclass or previous mixin application. This means that the innermost mixin is listed first. This may read backwards from the common order in JavaScript, but matches the order of language used to describe mixin application, like "S with A, B".

slots Slot[]

The shadow dom content slots that this element accepts.

source object

A reference to the source of a declaration or member.

1 nested properties
href string required

An absolute URL to the source (ie. a GitHub URL).

summary string

A markdown summary suitable for display in a listing.

superclass object

A reference to an export of a module.

All references are required to be publically accessible, so the canonical representation of a reference is the export it's available from.

package should generally refer to an npm package name. If package is undefined then the reference is local to this package. If module is undefined the reference is local to the containing module.

References to global symbols like Array, HTMLElement, or Event should use a package name of "global:".

3 nested properties
name string required
module string
package string
tagName string

An optional tag name that should be specified if this is a self-registering element.

Self-registering elements must also include a CustomElementExport in the module's exports.

CustomElementExport object

A global custom element defintion, ie the result of a customElements.define() call.

This is represented as an export because a definition makes the element available outside of the module it's defined it.

declaration object required

A reference to an export of a module.

All references are required to be publically accessible, so the canonical representation of a reference is the export it's available from.

package should generally refer to an npm package name. If package is undefined then the reference is local to this package. If module is undefined the reference is local to the containing module.

References to global symbols like Array, HTMLElement, or Event should use a package name of "global:".

3 nested properties
name string required
module string
package string
kind string required
Values: "custom-element-definition"
name string required

The tag name of the custom element.

deprecated string | boolean

Whether the custom-element export is deprecated. For example, a future version will not register the custom element in this file. If the value is a string, it's the reason for the deprecation.

CustomElementMixinDeclaration object

A class mixin that also adds custom element related properties.

customElement boolean required

Distinguishes a regular JavaScript class from a custom element class

Values: true
kind string required
Values: "mixin"
name string required
attributes Attribute[]

The attributes that this element is known to understand.

cssParts CssPart[]
cssProperties CssCustomProperty[]
cssStates CssCustomState[]
demos Demo[]
deprecated string | boolean

Whether the class or mixin is deprecated. If the value is a string, it's the reason for the deprecation.

description string

A markdown description of the class.

events Event[]

The events that this element fires.

members ClassField | ClassMethod[]
mixins Reference[]

Any class mixins applied in the extends clause of this class.

If mixins are applied in the class definition, then the true superclass of this class is the result of applying mixins in order to the superclass.

Mixins must be listed in order of their application to the superclass or previous mixin application. This means that the innermost mixin is listed first. This may read backwards from the common order in JavaScript, but matches the order of language used to describe mixin application, like "S with A, B".

parameters Parameter[]
return object
3 nested properties
description string

A markdown description.

summary string

A markdown summary suitable for display in a listing.

type object
3 nested properties
text string required

The full string representation of the type, in whatever type syntax is used, such as JSDoc, Closure, or TypeScript.

references TypeReference[]

An array of references to the types in the type string.

These references have optional indices into the type string so that tools can understand the references in the type string independently of the type system and syntax. For example, a documentation viewer could display the type Array<FooElement | BarElement> with cross-references to FooElement and BarElement without understanding arrays, generics, or union types.

source object

A reference to the source of a declaration or member.

slots Slot[]

The shadow dom content slots that this element accepts.

source object

A reference to the source of a declaration or member.

1 nested properties
href string required

An absolute URL to the source (ie. a GitHub URL).

summary string

A markdown summary suitable for display in a listing.

superclass object

A reference to an export of a module.

All references are required to be publically accessible, so the canonical representation of a reference is the export it's available from.

package should generally refer to an npm package name. If package is undefined then the reference is local to this package. If module is undefined the reference is local to the containing module.

References to global symbols like Array, HTMLElement, or Event should use a package name of "global:".

3 nested properties
name string required
module string
package string
tagName string

An optional tag name that should be specified if this is a self-registering element.

Self-registering elements must also include a CustomElementExport in the module's exports.

Demo object
url string required

Relative URL of the demo if it's published with the package. Absolute URL if it's hosted.

description string

A markdown description of the demo.

source object

A reference to the source of a declaration or member.

1 nested properties
href string required

An absolute URL to the source (ie. a GitHub URL).

Event object
name string required
type object required
3 nested properties
text string required

The full string representation of the type, in whatever type syntax is used, such as JSDoc, Closure, or TypeScript.

references TypeReference[]

An array of references to the types in the type string.

These references have optional indices into the type string so that tools can understand the references in the type string independently of the type system and syntax. For example, a documentation viewer could display the type Array<FooElement | BarElement> with cross-references to FooElement and BarElement without understanding arrays, generics, or union types.

source object

A reference to the source of a declaration or member.

1 nested properties
href string required

An absolute URL to the source (ie. a GitHub URL).

deprecated string | boolean

Whether the event is deprecated. If the value is a string, it's the reason for the deprecation.

description string

A markdown description.

inheritedFrom object

A reference to an export of a module.

All references are required to be publically accessible, so the canonical representation of a reference is the export it's available from.

package should generally refer to an npm package name. If package is undefined then the reference is local to this package. If module is undefined the reference is local to the containing module.

References to global symbols like Array, HTMLElement, or Event should use a package name of "global:".

3 nested properties
name string required
module string
package string
summary string

A markdown summary suitable for display in a listing.

FunctionDeclaration object
kind string required
Values: "function"
name string required
deprecated string | boolean

Whether the function is deprecated. If the value is a string, it's the reason for the deprecation.

description string

A markdown description.

parameters Parameter[]
return object
3 nested properties
description string

A markdown description.

summary string

A markdown summary suitable for display in a listing.

type object
3 nested properties
text string required

The full string representation of the type, in whatever type syntax is used, such as JSDoc, Closure, or TypeScript.

references TypeReference[]

An array of references to the types in the type string.

These references have optional indices into the type string so that tools can understand the references in the type string independently of the type system and syntax. For example, a documentation viewer could display the type Array<FooElement | BarElement> with cross-references to FooElement and BarElement without understanding arrays, generics, or union types.

source object

A reference to the source of a declaration or member.

source object

A reference to the source of a declaration or member.

1 nested properties
href string required

An absolute URL to the source (ie. a GitHub URL).

summary string

A markdown summary suitable for display in a listing.

JavaScriptExport object
declaration object required

A reference to an export of a module.

All references are required to be publically accessible, so the canonical representation of a reference is the export it's available from.

package should generally refer to an npm package name. If package is undefined then the reference is local to this package. If module is undefined the reference is local to the containing module.

References to global symbols like Array, HTMLElement, or Event should use a package name of "global:".

3 nested properties
name string required
module string
package string
kind string required
Values: "js"
name string required

The name of the exported symbol.

JavaScript has a number of ways to export objects which determine the correct name to use.

  • Default exports must use the name "default".
  • Named exports use the name that is exported. If the export is renamed with the "as" clause, use the exported name.
  • Aggregating exports (* from) should use the name *
deprecated string | boolean

Whether the export is deprecated. For example, the name of the export was changed. If the value is a string, it's the reason for the deprecation.

JavaScriptModule object
kind string required
Values: "javascript-module"
path string required

Path to the javascript file needed to be imported. (not the path for example to a typescript file.)

declarations ClassDeclaration | FunctionDeclaration | MixinDeclaration | VariableDeclaration | CustomElementDeclaration | CustomElementMixinDeclaration[]

The declarations of a module.

For documentation purposes, all declarations that are reachable from exports should be described here. Ie, functions and objects that may be properties of exported objects, or passed as arguments to functions.

deprecated string | boolean

Whether the module is deprecated. If the value is a string, it's the reason for the deprecation.

description string

A markdown description of the module.

exports JavaScriptExport | CustomElementExport[]

The exports of a module. This includes JavaScript exports and custom element definitions.

summary string

A markdown summary suitable for display in a listing.

MixinDeclaration object

A description of a class mixin.

Mixins are functions which generate a new subclass of a given superclass. This interfaces describes the class and custom element features that are added by the mixin. As such, it extends the CustomElement interface and ClassLike interface.

Since mixins are functions, it also extends the FunctionLike interface. This means a mixin is callable, and has parameters and a return type.

The return type is often hard or impossible to accurately describe in type systems like TypeScript. It requires generics and an extends operator that TypeScript lacks. Therefore it's recommended that the return type is left empty. The most common form of a mixin function takes a single argument, so consumers of this interface should assume that the return type is the single argument subclassed by this declaration.

A mixin should not have a superclass. If a mixins composes other mixins, they should be listed in the mixins field.

See [this article]{@link https://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/} for more information on the classmixin pattern in JavaScript.

kind string required
Values: "mixin"
name string required
deprecated string | boolean

Whether the class or mixin is deprecated. If the value is a string, it's the reason for the deprecation.

description string

A markdown description of the class.

members ClassField | ClassMethod[]
mixins Reference[]

Any class mixins applied in the extends clause of this class.

If mixins are applied in the class definition, then the true superclass of this class is the result of applying mixins in order to the superclass.

Mixins must be listed in order of their application to the superclass or previous mixin application. This means that the innermost mixin is listed first. This may read backwards from the common order in JavaScript, but matches the order of language used to describe mixin application, like "S with A, B".

parameters Parameter[]
return object
3 nested properties
description string

A markdown description.

summary string

A markdown summary suitable for display in a listing.

type object
3 nested properties
text string required

The full string representation of the type, in whatever type syntax is used, such as JSDoc, Closure, or TypeScript.

references TypeReference[]

An array of references to the types in the type string.

These references have optional indices into the type string so that tools can understand the references in the type string independently of the type system and syntax. For example, a documentation viewer could display the type Array<FooElement | BarElement> with cross-references to FooElement and BarElement without understanding arrays, generics, or union types.

source object

A reference to the source of a declaration or member.

source object

A reference to the source of a declaration or member.

1 nested properties
href string required

An absolute URL to the source (ie. a GitHub URL).

summary string

A markdown summary suitable for display in a listing.

superclass object

A reference to an export of a module.

All references are required to be publically accessible, so the canonical representation of a reference is the export it's available from.

package should generally refer to an npm package name. If package is undefined then the reference is local to this package. If module is undefined the reference is local to the containing module.

References to global symbols like Array, HTMLElement, or Event should use a package name of "global:".

3 nested properties
name string required
module string
package string
Parameter object
name string required
default string
deprecated string | boolean

Whether the property is deprecated. If the value is a string, it's the reason for the deprecation.

description string

A markdown description of the field.

optional boolean

Whether the parameter is optional. Undefined implies non-optional.

readonly boolean

Whether the property is read-only.

rest boolean

Whether the parameter is a rest parameter. Only the last parameter may be a rest parameter. Undefined implies single parameter.

summary string

A markdown summary suitable for display in a listing.

type object
3 nested properties
text string required

The full string representation of the type, in whatever type syntax is used, such as JSDoc, Closure, or TypeScript.

references TypeReference[]

An array of references to the types in the type string.

These references have optional indices into the type string so that tools can understand the references in the type string independently of the type system and syntax. For example, a documentation viewer could display the type Array<FooElement | BarElement> with cross-references to FooElement and BarElement without understanding arrays, generics, or union types.

source object

A reference to the source of a declaration or member.

1 nested properties
href string required

An absolute URL to the source (ie. a GitHub URL).

Privacy string
Reference object

A reference to an export of a module.

All references are required to be publically accessible, so the canonical representation of a reference is the export it's available from.

package should generally refer to an npm package name. If package is undefined then the reference is local to this package. If module is undefined the reference is local to the containing module.

References to global symbols like Array, HTMLElement, or Event should use a package name of "global:".

name string required
module string
package string
Slot object
name string required

The slot name, or the empty string for an unnamed slot.

deprecated string | boolean

Whether the slot is deprecated. If the value is a string, it's the reason for the deprecation.

description string

A markdown description.

summary string

A markdown summary suitable for display in a listing.

SourceReference object

A reference to the source of a declaration or member.

href string required

An absolute URL to the source (ie. a GitHub URL).

Type object
text string required

The full string representation of the type, in whatever type syntax is used, such as JSDoc, Closure, or TypeScript.

references TypeReference[]

An array of references to the types in the type string.

These references have optional indices into the type string so that tools can understand the references in the type string independently of the type system and syntax. For example, a documentation viewer could display the type Array<FooElement | BarElement> with cross-references to FooElement and BarElement without understanding arrays, generics, or union types.

source object

A reference to the source of a declaration or member.

1 nested properties
href string required

An absolute URL to the source (ie. a GitHub URL).

TypeReference object

A reference that is associated with a type string and optionally a range within the string.

Start and end must both be present or not present. If they're present, they are indices into the associated type string. If they are missing, the entire type string is the symbol referenced and the name should match the type string.

name string required
end number
module string
package string
start number
VariableDeclaration object
kind string required
Values: "variable"
name string required
default string
deprecated string | boolean

Whether the property is deprecated. If the value is a string, it's the reason for the deprecation.

description string

A markdown description of the field.

readonly boolean

Whether the property is read-only.

source object

A reference to the source of a declaration or member.

1 nested properties
href string required

An absolute URL to the source (ie. a GitHub URL).

summary string

A markdown summary suitable for display in a listing.

type object
3 nested properties
text string required

The full string representation of the type, in whatever type syntax is used, such as JSDoc, Closure, or TypeScript.

references TypeReference[]

An array of references to the types in the type string.

These references have optional indices into the type string so that tools can understand the references in the type string independently of the type system and syntax. For example, a documentation viewer could display the type Array<FooElement | BarElement> with cross-references to FooElement and BarElement without understanding arrays, generics, or union types.

source object

A reference to the source of a declaration or member.

1 nested properties
href string required

An absolute URL to the source (ie. a GitHub URL).