Skip to Content
🎉 @playcanvas/react 0.3.0! Now with React 19 support. Read more →
DocsAPIHooksuseMaterial

useMaterial

The useMaterial hook returns a StandardMaterial instance. This is useful if you need to create materials and apply them to Render components.

import { useMaterial } from '@playcanvas/react/hooks' /** * Create a red glowing box with a grain texture */ const RedGlowingBox = () => { // load a texture const { asset: grainTexture } = useTexture('./grain.jpg'); // create a material with the texture const material = useMaterial({ diffuse: 'red', emissive: 'red', emissiveIntensity: 10, diffuseMap: grainTexture, }); // return a box with the material return <Entity> <Render type="box" material={material} /> </Entity> };

Props

The StandardMaterial accepts a many different props which can be found here.

NameTypeDefault
alphaFadeboolean
ambientColor

The ambient color of the material. This color value is 3-component (RGB), where each component is between 0 and 1.

anisotropynumber

Defines amount of anisotropy. Requires StandardMaterial#enableGGXSpecular is set to true. - When anisotropy == 0, specular is isotropic. - When anisotropy < 0, anisotropy direction aligns with the tangent, and specular anisotropy increases as the anisotropy value decreases to minimum of -1. - When anisotropy > 0, anisotropy direction aligns with the bi-normal, and specular anisotropy increases as anisotropy value increases to maximum of 1.

aoIntensitynumber

Ambient occlusion intensity. Defaults to 1.

aoMapany

seMap The main (primary) diffuse map of the material (default is null).

aoMapChannelstring

Color channel of the main (primary) AO map to use. Can be “r”, “g”, “b” or “a”.

aoMapOffsetVec2

Controls the 2D offset of the main (primary) AO map. Each component is between 0 and 1.

aoMapRotationnumber

Controls the 2D rotation (in degrees) of the main (primary) AO map.

aoMapTilingVec2

Controls the 2D tiling of the main (primary) AO map.

aoMapUvnumber

Main (primary) AO map UV channel

aoDetailMapany

The main (primary) diffuse map of the material (default is null).

aoDetailMapChannelstring

Color channels of the detail (secondary) AO map to use. Can be “r”, “g”, “b” or “a” (default is “g”).

aoDetailMapOffsetVec2

Controls the 2D offset of the detail (secondary) AO map. Each component is between 0 and 1.

aoDetailMapRotationnumber

Controls the 2D rotation (in degrees) of the detail (secondary) AO map.

aoDetailMapTilingVec2

Controls the 2D tiling of the detail (secondary) AO map.

aoDetailMapUvnumber

Detail (secondary) AO map UV channel.

aoDetailModestring

Determines how the main (primary) and detail (secondary) AO maps are blended together. Can be: - DETAILMODE_MUL : Multiply together the primary and secondary colors. - DETAILMODE_ADD : Add together the primary and secondary colors. - DETAILMODE_SCREEN : Softer version of DETAILMODE_ADD . - DETAILMODE_OVERLAY : Multiplies or screens the colors, depending on the primary color. - DETAILMODE_MIN : Select whichever of the primary and secondary colors is darker, component-wise. - DETAILMODE_MAX : Select whichever of the primary and secondary colors is lighter, component-wise. Defaults to DETAILMODE_MUL .

aoVertexColorboolean

Use mesh vertex colors for AO. If aoMap is set, it’ll be multiplied by vertex colors.

aoVertexColorChannelstring

Vertex color channels to use for AO. Can be “r”, “g”, “b” or “a”.

bumpinessnumber

The bumpiness of the material. This value scales the assigned main (primary) normal map. It should be normally between 0 (no bump mapping) and 1 (full bump mapping), but can be set to e.g. 2 to give even more pronounced bump effect.

clearCoatnumber

Defines intensity of clearcoat layer from 0 to 1. Clearcoat layer is disabled when clearCoat == 0. Default value is 0 (disabled).

clearCoatBumpinessnumber

The bumpiness of the clearcoat layer. This value scales the assigned main clearcoat normal map. It should be normally between 0 (no bump mapping) and 1 (full bump mapping), but can be set to e.g. 2 to give even more pronounced bump effect.

clearCoatGlossInvertboolean

Invert the clearcoat gloss component (default is false). Enabling this flag results in material treating the clear coat gloss members as roughness.

clearCoatGlossMapany

in (primary) diffuse map of the material (default is null).

clearCoatGlossMapChannelstring

Color channel of the clearcoat gloss map to use. Can be “r”, “g”, “b” or “a”.

clearCoatGlossMapOffsetVec2

Controls the 2D offset of the clearcoat gloss map. Each component is between 0 and 1.

clearCoatGlossMapRotationnumber

Controls the 2D rotation (in degrees) of the clear coat gloss map.

clearCoatGlossMapTilingVec2

Controls the 2D tiling of the clearcoat gloss map.

clearCoatGlossMapUvnumber

Clearcoat gloss map UV channel.

clearCoatGlossVertexColorboolean

Use mesh vertex colors for clearcoat glossiness. If clearCoatGlossMap is set, it’ll be multiplied by vertex colors.

clearCoatGlossVertexColorChannelstring

Vertex color channel to use for clearcoat glossiness. Can be “r”, “g”, “b” or “a”.

clearCoatGlossnumber

Defines the clearcoat glossiness of the clearcoat layer from 0 (rough) to 1 (mirror).

clearCoatMapany

he main (primary) diffuse map of the material (default is null).

clearCoatMapChannelstring

Color channel of the clearcoat intensity map to use. Can be “r”, “g”, “b” or “a”.

clearCoatMapOffsetVec2

Controls the 2D offset of the clearcoat intensity map. Each component is between 0 and 1.

clearCoatMapRotationnumber

Controls the 2D rotation (in degrees) of the clearcoat intensity map.

clearCoatMapTilingVec2

Controls the 2D tiling of the clearcoat intensity map.

clearCoatMapUvnumber

Clearcoat intensity map UV channel.

clearCoatNormalMapany

n (primary) diffuse map of the material (default is null).

clearCoatNormalMapOffsetVec2

Controls the 2D offset of the main clearcoat normal map. Each component is between 0 and 1.

clearCoatNormalMapRotationnumber

Controls the 2D rotation (in degrees) of the main clearcoat map.

clearCoatNormalMapTilingVec2

Controls the 2D tiling of the main clearcoat normal map.

clearCoatNormalMapUvnumber

Clearcoat normal map UV channel.

clearCoatVertexColorboolean

Use mesh vertex colors for clearcoat intensity. If clearCoatMap is set, it’ll be multiplied by vertex colors.

clearCoatVertexColorChannelstring

Vertex color channel to use for clearcoat intensity. Can be “r”, “g”, “b” or “a”.

cubeMapany

Map The main (primary) diffuse map of the material (default is null).

cubeMapProjectionnumber

The type of projection applied to the cubeMap property: - CUBEPROJ_NONE : The cube map is treated as if it is infinitely far away. - CUBEPROJ_BOX : Box-projection based on a world space axis-aligned bounding box. Defaults to CUBEPROJ_NONE .

cubeMapProjectionBoxBoundingBox

The world space axis-aligned bounding box defining the box-projection used for the cubeMap property. Only used when cubeMapProjection is set to CUBEPROJ_BOX .

diffuseColor

The diffuse color of the material. This color value is 3-component (RGB), where each component is between 0 and 1. Defines basic surface color (aka albedo).

diffuseDetailMapany

ain (primary) diffuse map of the material (default is null).

diffuseDetailMapChannelstring

Color channels of the detail (secondary) diffuse map to use. Can be “r”, “g”, “b”, “a”, “rgb” or any swizzled combination.

diffuseDetailMapOffsetVec2

Controls the 2D offset of the detail (secondary) diffuse map. Each component is between 0 and 1.

diffuseDetailMapRotationnumber

Controls the 2D rotation (in degrees) of the main (secondary) diffuse map.

diffuseDetailMapTilingVec2

Controls the 2D tiling of the detail (secondary) diffuse map.

diffuseDetailMapUvnumber

Detail (secondary) diffuse map UV channel.

diffuseDetailModestring

Determines how the main (primary) and detail (secondary) diffuse maps are blended together. Can be: - DETAILMODE_MUL : Multiply together the primary and secondary colors. - DETAILMODE_ADD : Add together the primary and secondary colors. - DETAILMODE_SCREEN : Softer version of DETAILMODE_ADD . - DETAILMODE_OVERLAY : Multiplies or screens the colors, depending on the primary color. - DETAILMODE_MIN : Select whichever of the primary and secondary colors is darker, component-wise. - DETAILMODE_MAX : Select whichever of the primary and secondary colors is lighter, component-wise. Defaults to DETAILMODE_MUL .

diffuseMapany

The main (primary) diffuse map of the material (default is null).

diffuseMapChannelstring

Color channels of the main (primary) diffuse map to use. Can be “r”, “g”, “b”, “a”, “rgb” or any swizzled combination.

diffuseMapOffsetVec2

Controls the 2D offset of the main (primary) diffuse map. Each component is between 0 and 1.

diffuseMapRotationnumber

Controls the 2D rotation (in degrees) of the main (primary) diffuse map.

diffuseMapTilingVec2

Controls the 2D tiling of the main (primary) diffuse map.

diffuseMapUvnumber

Main (primary) diffuse map UV channel.

diffuseVertexColorboolean

Multiply diffuse by the mesh vertex colors.

diffuseVertexColorChannelstring

Vertex color channels to use for diffuse. Can be “r”, “g”, “b”, “a”, “rgb” or any swizzled combination.

emissiveColor

The emissive color of the material. This color value is 3-component (RGB), where each component is between 0 and 1.

emissiveIntensitynumber

Emissive color multiplier.

emissiveMapany

The main (primary) diffuse map of the material (default is null).

emissiveMapChannelstring

Color channels of the emissive map to use. Can be “r”, “g”, “b”, “a”, “rgb” or any swizzled combination.

emissiveMapOffsetVec2

Controls the 2D offset of the emissive map. Each component is between 0 and 1.

emissiveMapRotationnumber

Controls the 2D rotation (in degrees) of the emissive map.

emissiveMapTilingVec2

Controls the 2D tiling of the emissive map.

emissiveMapUvnumber

Emissive map UV channel.

emissiveVertexColorboolean

Use mesh vertex colors for emission. If emissiveMap or emissive are set, they’ll be multiplied by vertex colors.

emissiveVertexColorChannelstring

Vertex color channels to use for emission. Can be “r”, “g”, “b”, “a”, “rgb” or any swizzled combination.

enableGGXSpecularboolean

Enables GGX specular. Also enables StandardMaterial#anisotropy parameter to set material anisotropy.

envAtlasany

ap The main (primary) diffuse map of the material (default is null).

fresnelModelnumber

Defines the formula used for Fresnel effect. As a side-effect, enabling any Fresnel model changes the way diffuse and reflection components are combined. When Fresnel is off, legacy non energy-conserving combining is used. When it is on, combining behavior is energy-conserving. - FRESNEL_NONE : No Fresnel. - FRESNEL_SCHLICK : Schlick’s approximation of Fresnel (recommended). Parameterized by specular color.

glossnumber

Defines the glossiness of the material from 0 (rough) to 1 (shiny).

glossInvertboolean

Invert the gloss component (default is false). Enabling this flag results in material treating the gloss members as roughness.

glossMapany

ap The main (primary) diffuse map of the material (default is null).

glossMapChannelstring

Color channel of the gloss map to use. Can be “r”, “g”, “b” or “a”.

glossMapOffsetVec2

Controls the 2D offset of the gloss map. Each component is between 0 and 1.

glossMapRotationnumber

Controls the 2D rotation (in degrees) of the gloss map.

glossMapTilingVec2

Controls the 2D tiling of the gloss map.

glossMapUvnumber

Gloss map UV channel.

glossVertexColorboolean

Use mesh vertex colors for glossiness. If glossMap is set, it’ll be multiplied by vertex colors.

glossVertexColorChannelstring

Vertex color channel to use for glossiness. Can be “r”, “g”, “b” or “a”.

heightMapany

p The main (primary) diffuse map of the material (default is null).

heightMapChannelstring

Color channel of the height map to use. Can be “r”, “g”, “b” or “a”.

heightMapFactornumber

Height map multiplier. Affects the strength of the parallax effect.

heightMapOffsetVec2

Controls the 2D offset of the height map. Each component is between 0 and 1.

heightMapRotationnumber

Controls the 2D rotation (in degrees) of the height map.

heightMapTilingVec2

Controls the 2D tiling of the height map.

heightMapUvnumber

Height map UV channel.

lightMapany

ap The main (primary) diffuse map of the material (default is null).

lightMapChannelstring

Color channels of the lightmap to use. Can be “r”, “g”, “b”, “a”, “rgb” or any swizzled combination.

lightMapOffsetVec2

Controls the 2D offset of the lightmap. Each component is between 0 and 1.

lightMapRotationnumber

Controls the 2D rotation (in degrees) of the lightmap.

lightMapTilingVec2

Controls the 2D tiling of the lightmap.

lightMapUvnumber

Lightmap UV channel

lightVertexColorboolean

Use baked vertex lighting. If lightMap is set, it’ll be multiplied by vertex colors.

lightVertexColorChannelstring

Vertex color channels to use for baked lighting. Can be “r”, “g”, “b”, “a”, “rgb” or any swizzled combination.

metalnessnumber

Defines how much the surface is metallic. From 0 (dielectric) to 1 (metal).

metalnessMapany

he main (primary) diffuse map of the material (default is null).

metalnessMapChannelstring

Color channel of the metalness map to use. Can be “r”, “g”, “b” or “a”.

metalnessMapOffsetVec2

Controls the 2D offset of the metalness map. Each component is between 0 and 1.

metalnessMapRotationnumber

Controls the 2D rotation (in degrees) of the metalness map.

metalnessMapTilingVec2

Controls the 2D tiling of the metalness map.

metalnessMapUvnumber

Metalness map UV channel.

metalnessVertexColorboolean

Use mesh vertex colors for metalness. If metalnessMap is set, it’ll be multiplied by vertex colors.

metalnessVertexColorChannelstring

Vertex color channel to use for metalness. Can be “r”, “g”, “b” or “a”.

normalDetailMapany

main (primary) diffuse map of the material (default is null).

normalDetailMapBumpinessnumber

The bumpiness of the material. This value scales the assigned detail (secondary) normal map. It should be normally between 0 (no bump mapping) and 1 (full bump mapping), but can be set to e.g. 2 to give even more pronounced bump effect.

normalDetailMapOffsetVec2

Controls the 2D offset of the detail (secondary) normal map. Each component is between 0 and 1.

normalDetailMapRotationnumber

Controls the 2D rotation (in degrees) of the detail (secondary) normal map.

normalDetailMapTilingVec2

Controls the 2D tiling of the detail (secondary) normal map.

normalDetailMapUvnumber

Detail (secondary) normal map UV channel.

normalMapany

p The main (primary) diffuse map of the material (default is null).

normalMapOffsetVec2

Controls the 2D offset of the main (primary) normal map. Each component is between 0 and 1.

normalMapRotationnumber

Controls the 2D rotation (in degrees) of the main (primary) normal map.

normalMapTilingVec2

Controls the 2D tiling of the main (primary) normal map.

normalMapUvnumber

Main (primary) normal map UV channel.

occludeDirectnumber
occludeSpecularnumber

Uses ambient occlusion to darken specular/reflection. It’s a hack, because real specular occlusion is view-dependent. However, it can be better than nothing. - SPECOCC_NONE : No specular occlusion - SPECOCC_AO : Use AO directly to occlude specular. - SPECOCC_GLOSSDEPENDENT : Modify AO based on material glossiness/view angle to occlude specular.

occludeSpecularIntensitynumber

Controls visibility of specular occlusion.

opacitynumber

The opacity of the material. This value can be between 0 and 1, where 0 is fully transparent and 1 is fully opaque. If you want the material to be semi-transparent you also need to set the Material#blendType to BLEND_NORMAL , BLEND_ADDITIVE or any other mode. Also note that for most semi-transparent objects you want Material#depthWrite to be false, otherwise they can fully occlude objects behind them.

opacityDitherstring

Used to specify whether opacity is dithered, which allows transparency without alpha blending. Can be: - DITHER_NONE : Opacity dithering is disabled. - DITHER_BAYER8 : Opacity is dithered using a Bayer 8 matrix. - DITHER_BLUENOISE : Opacity is dithered using a blue noise. - DITHER_IGNNOISE : Opacity is dithered using an interleaved gradient noise. Defaults to DITHER_NONE .

opacityShadowDitherstring
opacityFadesSpecularboolean

Used to specify whether specular and reflections are faded out using StandardMaterial#opacity . Default is true. When set to false use Material#alphaFade to fade out materials.

opacityMapany

The main (primary) diffuse map of the material (default is null).

opacityMapChannelstring

Color channel of the opacity map to use. Can be “r”, “g”, “b” or “a”.

opacityMapOffsetVec2

Controls the 2D offset of the opacity map. Each component is between 0 and 1.

opacityMapRotationnumber

Controls the 2D rotation (in degrees) of the opacity map.

opacityMapTilingVec2

Controls the 2D tiling of the opacity map.

opacityMapUvnumber

Opacity map UV channel.

opacityVertexColorboolean

Use mesh vertex colors for opacity. If opacityMap is set, it’ll be multiplied by vertex colors.

opacityVertexColorChannelstring

Vertex color channels to use for opacity. Can be “r”, “g”, “b” or “a”.

pixelSnapboolean

Align vertices to pixel coordinates when rendering. Useful for pixel perfect 2D graphics.

reflectivitynumber

Environment map intensity.

refractionnumber

Defines the visibility of refraction. Material can refract the same cube map as used for reflections.

refractionIndexnumber

Defines the index of refraction, i.e. The amount of distortion. The value is calculated as (outerIor / surfaceIor), where inputs are measured indices of refraction, the one around the object and the one of its own surface. In most situations outer medium is air, so outerIor will be approximately 1. Then you only need to do (1.0 / surfaceIor).

dispersionnumber

The strength of the angular separation of colors (chromatic aberration) transmitting through a volume. Defaults to 0, which is equivalent to no dispersion.

shadowCatcherboolean

When enabled, the material will output accumulated directional shadow value in linear space as the color.

specularColor

The specular color of the material. This color value is 3-component (RGB), where each component is between 0 and 1. Defines surface reflection/specular color. Affects specular intensity and tint.

specularMapany

The main (primary) diffuse map of the material (default is null).

specularMapChannelstring

Color channels of the specular map to use. Can be “r”, “g”, “b”, “a”, “rgb” or any swizzled combination.

specularMapOffsetVec2

Controls the 2D offset of the specular map. Each component is between 0 and 1.

specularMapRotationnumber

Controls the 2D rotation (in degrees) of the specular map.

specularMapTilingVec2

Controls the 2D tiling of the specular map.

specularMapUvnumber

Specular map UV channel.

specularTintboolean

Multiply specular map and/or specular vertex color by the constant specular value.

specularVertexColorboolean

Use mesh vertex colors for specular. If specularMap or are specularTint are set, they’ll be multiplied by vertex colors.

specularVertexColorChannelstring

Vertex color channels to use for specular. Can be “r”, “g”, “b”, “a”, “rgb” or any swizzled combination.

specularityFactornumber

The factor of specular intensity, used to weight the fresnel and specularity. Default is 1.0.

specularityFactorMapany

(primary) diffuse map of the material (default is null).

specularityFactorMapChannelstring

The channel used by the specularity factor texture to sample from (default is ‘a’).

specularityFactorMapOffsetVec2

Controls the 2D offset of the specularity factor map. Each component is between 0 and 1.

specularityFactorMapRotationnumber

Controls the 2D rotation (in degrees) of the specularity factor map.

specularityFactorMapTilingVec2

Controls the 2D tiling of the specularity factor map.

specularityFactorMapUvnumber

Specularity factor map UV channel.

useSheenboolean

Toggle sheen specular effect on/off.

sheenColor

The specular color of the sheen (fabric) microfiber structure. This color value is 3-component (RGB), where each component is between 0 and 1.

sheenMapany

ap The main (primary) diffuse map of the material (default is null).

sheenMapChannelstring

Color channels of the sheen map to use. Can be “r”, “g”, “b”, “a”, “rgb” or any swizzled combination.

sheenMapOffsetVec2

Controls the 2D offset of the sheen map. Each component is between 0 and 1.

sheenMapRotationnumber

Controls the 2D rotation (in degrees) of the sheen map.

sheenMapTilingVec2

Controls the 2D tiling of the sheen map.

sheenMapUvnumber

Sheen map UV channel.

sheenVertexColorboolean

Use mesh vertex colors for sheen. If sheen map or sheen tint are set, they’ll be multiplied by vertex colors.

sheenVertexColorChannelstring
sphereMapany

p The main (primary) diffuse map of the material (default is null).

twoSidedLightingboolean

Calculate proper normals (and therefore lighting) on backfaces.

useFogboolean

Apply fogging (as configured in scene settings)

useTonemapboolean

Apply tonemapping (as configured in Scene#rendering or CameraComponent.rendering ). Defaults to true.

useLightingboolean

Apply lighting

useMetalnessboolean

Use metalness properties instead of specular. When enabled, diffuse colors also affect specular instead of the dedicated specular map. This can be used as alternative to specular color to save space. With metalness == 0, the pixel is assumed to be dielectric, and diffuse color is used as normal. With metalness == 1, the pixel is fully metallic, and diffuse color is used as specular color instead.

useMetalnessSpecularColorboolean

When metalness is enabled, use the specular map to apply color tint to specular reflections. at direct angles.

useSkyboxboolean

Apply scene skybox as prefiltered environment map

Last updated on