# MaterialElement

Class · extends `HTMLElement` · category: Resources

Source: https://github.com/playcanvas/web-components/blob/252f001881302c266c8d727044408c32be2bb5e7/src/material.ts#L209

The MaterialElement interface provides properties and methods for manipulating
[`<pc-material>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-material/) elements.
The MaterialElement interface also inherits the properties and methods of the
[HTMLElement](https://developer.mozilla.org/docs/Web/API/HTMLElement) interface.

A `pc-material` must be a direct child of `pc-app` — elements placed elsewhere log a warning
and never create a material. Elements inserted while the application is already running are
created on insertion.

The element is metal/rough by default: unlike a bare `StandardMaterial` it enables the metalness
workflow, which is what the `metalness-*` attributes assume and what glTF means by PBR. It also
defaults `metalness` to 0 rather than the engine's 1, because those two defaults have to be
chosen together - the engine's 1 is unreachable under its own `useMetalness` of false, and with
the workflow on it would make every material fully metallic, so `<pc-material diffuse="crimson">`
would render as dark tinted reflections of an environment that may not exist rather than as a
crimson surface. `metalness="1"` remains one attribute away.

The `roughness` and `roughness-map` attributes are aliases for `gloss` and `gloss-map` that
additionally invert the gloss channel; do not mix the two families on one element.

The two aliases are documented here rather than on an accessor, because they resolve to the
`gloss` properties and would otherwise inherit gloss's description - which reads inverted.

**elementSummary** The `<pc-material>` element defines a physically based material, which
`<pc-render>` elements apply by naming its `id`. It is metal/rough by default, with `metalness`
starting at 0. Must be a direct child of `<pc-app>`.

**attribute** roughness - The roughness of the material, from 0 (shiny) to 1 (rough). An
alias for `gloss` that also inverts it, so do not combine it with the `gloss` attributes.

**attribute** roughness-map - The id of the `pc-asset` to use as the roughness map. An
alias for `gloss-map` that also inverts the gloss channel, so do not combine it with the `gloss`
attributes.

## Properties

### material

```ts
material: StandardMaterial | null = null
```

The material. `null` until the containing application has created it — an element present
at startup has its material once the application is ready.

## Accessors

### alphaDither

```ts
get alphaDither(): number | null
set alphaDither(value: number | null)
```

Gets the alpha used by opacity dithering, which needs an `opacity-dither` mode other than
`none`.

### alphaTest

```ts
get alphaTest(): number
set alphaTest(value: number)
```

Gets the alpha test reference value.

### alphaToCoverage

```ts
get alphaToCoverage(): boolean
set alphaToCoverage(value: boolean)
```

Gets whether to use alpha to coverage.

### aoIntensity

```ts
get aoIntensity(): number
set aoIntensity(value: number)
```

Gets the strength of the ambient occlusion map.

### aoMap

```ts
get aoMap(): string
set aoMap(value: string)
```

Gets the id of the `pc-asset` used as the ambient occlusion map.

### aoMapChannel

```ts
get aoMapChannel(): ScalarChannel
set aoMapChannel(value: ScalarChannel)
```

Gets the color channel of the ambient occlusion map to sample.

### aoMapOffset

```ts
get aoMapOffset(): Vec2
set aoMapOffset(value: Vec2)
```

Gets the 2D offset of the ambient occlusion map.

### aoMapRotation

```ts
get aoMapRotation(): number
set aoMapRotation(value: number)
```

Gets the 2D rotation of the ambient occlusion map.

### aoMapTiling

```ts
get aoMapTiling(): Vec2
set aoMapTiling(value: Vec2)
```

Gets the 2D tiling of the ambient occlusion map.

### aoMapUv

```ts
get aoMapUv(): number
set aoMapUv(value: number)
```

Gets the UV channel the ambient occlusion map samples.

### blendType

```ts
get blendType(): BlendType
set blendType(value: BlendType)
```

Gets how the material is blended with the scene behind it.

### bumpiness

```ts
get bumpiness(): number
set bumpiness(value: number)
```

Gets the strength of the normal map.

### cull

```ts
get cull(): CullMode
set cull(value: CullMode)
```

Gets which faces of a mesh are culled.

### depthBias

```ts
get depthBias(): number
set depthBias(value: number)
```

Gets the offset applied to the depth of a fragment.

### depthTest

```ts
get depthTest(): boolean
set depthTest(value: boolean)
```

Gets whether fragments are tested against the depth buffer.

### depthWrite

```ts
get depthWrite(): boolean
set depthWrite(value: boolean)
```

Gets whether fragments write to the depth buffer.

### diffuse

```ts
get diffuse(): Color
set diffuse(value: Color)
```

Gets the diffuse color of the material.

### diffuseMap

```ts
get diffuseMap(): string
set diffuseMap(value: string)
```

Gets the id of the `pc-asset` used as the diffuse map.

### diffuseMapChannel

```ts
get diffuseMapChannel(): ColorChannel
set diffuseMapChannel(value: ColorChannel)
```

Gets the color channels of the diffuse map to sample.

### diffuseMapOffset

```ts
get diffuseMapOffset(): Vec2
set diffuseMapOffset(value: Vec2)
```

Gets the 2D offset of the diffuse map.

### diffuseMapRotation

```ts
get diffuseMapRotation(): number
set diffuseMapRotation(value: number)
```

Gets the 2D rotation of the diffuse map.

### diffuseMapTiling

```ts
get diffuseMapTiling(): Vec2
set diffuseMapTiling(value: Vec2)
```

Gets the 2D tiling of the diffuse map.

### diffuseMapUv

```ts
get diffuseMapUv(): number
set diffuseMapUv(value: number)
```

Gets the UV channel the diffuse map samples.

### emissive

```ts
get emissive(): Color
set emissive(value: Color)
```

Gets the emissive color of the material.

### emissiveIntensity

```ts
get emissiveIntensity(): number
set emissiveIntensity(value: number)
```

Gets the multiplier applied to the emissive color and map.

### emissiveMap

```ts
get emissiveMap(): string
set emissiveMap(value: string)
```

Gets the id of the `pc-asset` used as the emissive map.

### emissiveMapChannel

```ts
get emissiveMapChannel(): ColorChannel
set emissiveMapChannel(value: ColorChannel)
```

Gets the color channels of the emissive map to sample.

### emissiveMapOffset

```ts
get emissiveMapOffset(): Vec2
set emissiveMapOffset(value: Vec2)
```

Gets the 2D offset of the emissive map.

### emissiveMapRotation

```ts
get emissiveMapRotation(): number
set emissiveMapRotation(value: number)
```

Gets the 2D rotation of the emissive map.

### emissiveMapTiling

```ts
get emissiveMapTiling(): Vec2
set emissiveMapTiling(value: Vec2)
```

Gets the 2D tiling of the emissive map.

### emissiveMapUv

```ts
get emissiveMapUv(): number
set emissiveMapUv(value: number)
```

Gets the UV channel the emissive map samples.

### enableGGXSpecular

```ts
get enableGGXSpecular(): boolean
set enableGGXSpecular(value: boolean)
```

Gets whether to use the GGX specular model.

### flatShading

```ts
get flatShading(): boolean
set flatShading(value: boolean)
```

Gets whether the material is shaded with the geometric normal of each triangle.

### fresnelModel

```ts
get fresnelModel(): FresnelModel
set fresnelModel(value: FresnelModel)
```

Gets the Fresnel model used for specular reflections at grazing angles.

### gloss

```ts
get gloss(): number
set gloss(value: number)
```

Gets the glossiness of the material.

### glossInvert

```ts
get glossInvert(): boolean
set glossInvert(value: boolean)
```

Gets whether the gloss value and map are inverted.

### glossMap

```ts
get glossMap(): string
set glossMap(value: string)
```

Gets the id of the `pc-asset` used as the gloss map.

### glossMapChannel

```ts
get glossMapChannel(): ScalarChannel
set glossMapChannel(value: ScalarChannel)
```

Gets the color channel of the gloss map to sample.

### glossMapOffset

```ts
get glossMapOffset(): Vec2
set glossMapOffset(value: Vec2)
```

Gets the 2D offset of the gloss map.

### glossMapRotation

```ts
get glossMapRotation(): number
set glossMapRotation(value: number)
```

Gets the 2D rotation of the gloss map.

### glossMapTiling

```ts
get glossMapTiling(): Vec2
set glossMapTiling(value: Vec2)
```

Gets the 2D tiling of the gloss map.

### glossMapUv

```ts
get glossMapUv(): number
set glossMapUv(value: number)
```

Gets the UV channel the gloss map samples.

### heightMap

```ts
get heightMap(): string
set heightMap(value: string)
```

Gets the id of the `pc-asset` used as the height map.

### heightMapBase

```ts
get heightMapBase(): number
set heightMapBase(value: number)
```

Gets the height map value that sits at the level of the geometry.

### heightMapChannel

```ts
get heightMapChannel(): ScalarChannel
set heightMapChannel(value: ScalarChannel)
```

Gets the color channel of the height map to sample.

### heightMapFactor

```ts
get heightMapFactor(): number
set heightMapFactor(value: number)
```

Gets the strength of the parallax effect driven by the height map.

### heightMapOffset

```ts
get heightMapOffset(): Vec2
set heightMapOffset(value: Vec2)
```

Gets the 2D offset of the height map.

### heightMapRotation

```ts
get heightMapRotation(): number
set heightMapRotation(value: number)
```

Gets the 2D rotation of the height map.

### heightMapTiling

```ts
get heightMapTiling(): Vec2
set heightMapTiling(value: Vec2)
```

Gets the 2D tiling of the height map.

### heightMapUv

```ts
get heightMapUv(): number
set heightMapUv(value: number)
```

Gets the UV channel the height map samples.

### metalness

```ts
get metalness(): number
set metalness(value: number)
```

Gets how metallic the surface is.

### metalnessMap

```ts
get metalnessMap(): string
set metalnessMap(value: string)
```

Gets the id of the `pc-asset` used as the metalness map.

### metalnessMapChannel

```ts
get metalnessMapChannel(): ScalarChannel
set metalnessMapChannel(value: ScalarChannel)
```

Gets the color channel of the metalness map to sample.

### metalnessMapOffset

```ts
get metalnessMapOffset(): Vec2
set metalnessMapOffset(value: Vec2)
```

Gets the 2D offset of the metalness map.

### metalnessMapRotation

```ts
get metalnessMapRotation(): number
set metalnessMapRotation(value: number)
```

Gets the 2D rotation of the metalness map.

### metalnessMapTiling

```ts
get metalnessMapTiling(): Vec2
set metalnessMapTiling(value: Vec2)
```

Gets the 2D tiling of the metalness map.

### metalnessMapUv

```ts
get metalnessMapUv(): number
set metalnessMapUv(value: number)
```

Gets the UV channel the metalness map samples.

### name

```ts
get name(): string
set name(value: string)
```

Gets the name of the material - the label shown wherever materials surface by name, such
as profilers, GPU captures and the assignments `pc-model.hierarchy()` reports. Purely a
label: element references resolve through `id`.

### normalMap

```ts
get normalMap(): string
set normalMap(value: string)
```

Gets the id of the `pc-asset` used as the normal map.

### normalMapOffset

```ts
get normalMapOffset(): Vec2
set normalMapOffset(value: Vec2)
```

Gets the 2D offset of the normal map.

### normalMapRotation

```ts
get normalMapRotation(): number
set normalMapRotation(value: number)
```

Gets the 2D rotation of the normal map.

### normalMapTiling

```ts
get normalMapTiling(): Vec2
set normalMapTiling(value: Vec2)
```

Gets the 2D tiling of the normal map.

### normalMapUv

```ts
get normalMapUv(): number
set normalMapUv(value: number)
```

Gets the UV channel the normal map samples.

### occludeDirect

```ts
get occludeDirect(): boolean
set occludeDirect(value: boolean)
```

Gets whether ambient occlusion also attenuates direct lighting.

### occludeSpecular

```ts
get occludeSpecular(): OccludeSpecular
set occludeSpecular(value: OccludeSpecular)
```

Gets how specular reflections are occluded.

### opacity

```ts
get opacity(): number
set opacity(value: number)
```

Gets the opacity of the material, which requires a `blend-type` other than `none` to have
any visible effect.

### opacityDither

```ts
get opacityDither(): OpacityDither
set opacityDither(value: OpacityDither)
```

Gets the dithering used to render opacity.

### opacityFadesSpecular

```ts
get opacityFadesSpecular(): boolean
set opacityFadesSpecular(value: boolean)
```

Gets whether specular highlights fade out as the material becomes transparent.

### opacityMap

```ts
get opacityMap(): string
set opacityMap(value: string)
```

Gets the id of the `pc-asset` used as the opacity map.

### opacityMapChannel

```ts
get opacityMapChannel(): ScalarChannel
set opacityMapChannel(value: ScalarChannel)
```

Gets the color channel of the opacity map to sample.

### opacityMapOffset

```ts
get opacityMapOffset(): Vec2
set opacityMapOffset(value: Vec2)
```

Gets the 2D offset of the opacity map.

### opacityMapRotation

```ts
get opacityMapRotation(): number
set opacityMapRotation(value: number)
```

Gets the 2D rotation of the opacity map.

### opacityMapTiling

```ts
get opacityMapTiling(): Vec2
set opacityMapTiling(value: Vec2)
```

Gets the 2D tiling of the opacity map.

### opacityMapUv

```ts
get opacityMapUv(): number
set opacityMapUv(value: number)
```

Gets the UV channel the opacity map samples.

### parallaxMode

```ts
get parallaxMode(): ParallaxMode
set parallaxMode(value: ParallaxMode)
```

Gets how the height map offsets the UVs of the other maps.

### parallaxSamples

```ts
get parallaxSamples(): number
set parallaxSamples(value: number)
```

Gets the maximum number of height map taps along the view ray, which applies only when
`parallax-mode` is `occlusion`.

### parallaxShadowSamples

```ts
get parallaxShadowSamples(): number
set parallaxShadowSamples(value: number)
```

Gets the maximum number of height map taps towards each directional light, which applies
only when `parallax-mode` is `occlusion`.

### roughness

```ts
get roughness(): number
set roughness(value: number)
```

Gets the roughness of the material.

### roughnessMap

```ts
get roughnessMap(): string
set roughnessMap(value: string)
```

Gets the id of the `pc-asset` used as the roughness map.

### slopeDepthBias

```ts
get slopeDepthBias(): number
set slopeDepthBias(value: number)
```

Gets the depth offset applied in proportion to a surface's slope.

### specular

```ts
get specular(): Color
set specular(value: Color)
```

Gets the specular color of the material, which applies only when the metalness workflow is
disabled or `use-metalness-specular-color` is enabled.

### specularityFactor

```ts
get specularityFactor(): number
set specularityFactor(value: number)
```

Gets the strength of specular reflections at direct angles, which applies only when
`use-metalness-specular-color` is enabled.

### twoSidedLighting

```ts
get twoSidedLighting(): boolean
set twoSidedLighting(value: boolean)
```

Gets whether back faces are lit as though their normals were flipped.

### useFog

```ts
get useFog(): boolean
set useFog(value: boolean)
```

Gets whether the material is affected by scene fog.

### useLighting

```ts
get useLighting(): boolean
set useLighting(value: boolean)
```

Gets whether the material is affected by scene lights.

### useMetalness

```ts
get useMetalness(): boolean
set useMetalness(value: boolean)
```

Gets whether to use the metalness workflow.

### useMetalnessSpecularColor

```ts
get useMetalnessSpecularColor(): boolean
set useMetalnessSpecularColor(value: boolean)
```

Gets whether the specular color tints reflections while the metalness workflow is in use.

### useSkybox

```ts
get useSkybox(): boolean
set useSkybox(value: boolean)
```

Gets whether the material is lit by the scene's skybox.

### useTonemap

```ts
get useTonemap(): boolean
set useTonemap(value: boolean)
```

Gets whether the camera's tone mapping is applied to the material.

## Methods

### get

```ts
static get(id: string): StandardMaterial | null | undefined
```

Returns the [StandardMaterial](https://api.playcanvas.com/engine/classes/StandardMaterial.html) created by the `<pc-material>` element with the given
`id`, or `undefined` if there is no such element or its material has not been created yet.

**Parameters**

- `id` (`string`): The `id` of the `<pc-material>` element.

**Returns** `StandardMaterial | null | undefined`: The material, or `undefined`.