Material

A surface appearance that can be applied to faces — color, texture, transparency, or PBR properties.

Materials control how geometry looks when rendered. A material can be a simple flat color, a color with transparency, a texture image, or (in SketchUp 2025+) a full PBR material with metallic, roughness, normal, and ambient occlusion maps.

You create materials inside an operation with op.createMaterial(), then apply them to faces. Query all materials in the model with model.getMaterials().

See the Material Examples for more ways to use them.

Example

let model = await SketchUpApi.getActiveModel();

// Create a colored material and apply it
await model.performOperation(async op => {
  const matRef = op.createMaterial('Blue Glass');
  op.materialSetColor(
    matRef, new SketchUpApi.Color(100, 150, 255)
  );
  op.materialSetAlpha(matRef, 0.5);

  const faceRef = op.createFace(model, [
    [0, 0, 0], [60, 0, 0],
    [60, 60, 0], [0, 60, 0]
  ]);
  op.faceSetFrontMaterial(faceRef, matRef);
}, 'Create blue glass face');

// Query materials back
let materials = await model.getMaterials();
let mat = materials.values.find(
  m => m.name === 'Blue Glass'
);
console.log(mat.color.toHex());
// => #6496FFFF
console.log(mat.alpha);
// => 0.5

See

Properties

alpha

readonly alpha: number

Opacity from 0 (fully transparent) to 1 (fully opaque). Set via op.materialSetAlpha(matRef, value).

ambientOcclusion

readonly ambientOcclusion: Readonly<AmbientOcclusionTextureInfo>

Ambient occlusion map settings (PBR workflow only). Ignored when workflow is not PBR.

attributes

readonly attributes: Attributes

Custom attribute dictionaries attached to this material.

color

readonly color: Color

The solid color of this material. Even textured materials have a color that shows through transparent texture areas.

colorizeDeltas

readonly colorizeDeltas: readonly [number, number, number]

HSL deltas applied when colorizing: [hue, saturation, lightness].

colorizeType

readonly colorizeType: MaterialColorizeType

How the colorize effect is blended with the texture.

displayName

readonly displayName: string

The user-visible name shown in the Materials panel, like "Brick_Antique". May differ from name for built-in materials that have localized display names.

id

readonly id: number

The persistent ID that uniquely identifies this material.

materialType

readonly materialType: MaterialType

Whether this material uses color only, texture, or both.

metallic

readonly metallic: Readonly<MetallicTextureInfo>

Metallic map settings (PBR workflow only). Ignored when workflow is not PBR.

name

readonly name: string

The internal name used to reference this material in API calls, like "Brick_Antique".

normal

readonly normal: Readonly<NormalTextureInfo>

Normal map settings (PBR workflow only). Ignored when workflow is not PBR.

ownerType

readonly ownerType: MaterialOwnerType

What kind of entity owns this material (model-level, layer, etc).

roughness

readonly roughness: Readonly<RoughnessTextureInfo>

Roughness map settings (PBR workflow only). Ignored when workflow is not PBR.

texture

readonly texture: Texture | undefined

The texture image applied to this material, or undefined if it’s a solid-color material. Access texture.imageWidth and texture.imageHeight for pixel dimensions.

Since

SDK 2.12.0 Protocol 1.9.0

type

readonly type: Material = EntityType.Material

useAlpha

readonly useAlpha: boolean

Whether the alpha channel is actively used for rendering.

workflow

readonly workflow: MaterialWorkflow

Whether this material uses the classic workflow or PBR (physically-based rendering). PBR is only available in SketchUp 2025 and later.

Since

SDK 2.12.0 Protocol 1.9.0

Accessors

sketchupId

Get Signature

get sketchupId(): SketchupId

JS API identifier for this material. Pass it to API methods that accept a sketchupId.

Returns

SketchupId

typeName

Get Signature

get typeName(): string

Returns a named variant of the type field.

Since

SDK 2.35.0

Returns

string

Methods

exportThumbnail()

exportThumbnail(fileType, options): Promise<string>

Exports a thumbnail preview of this material as a base64-encoded image. For solid colors the result is a square; for textured materials the aspect ratio is preserved and maxSize limits the largest dimension.

Parameters

Parameter	Type	Description
`fileType`	`ImageFileType`	`'png'`, `'jpg'`, or `'webp'`
`options`	{ `maxSize`: `number`; }	`{ maxSize }` — max pixel dimension
`options.maxSize`	`number`	‐

Returns

Promise<string>

Since

SDK 2.15.0 Protocol 1.12.0

getSkm()

getSkm(): Promise<string>

Exports this material as a .skm file (SketchUp Material format) and returns the data as a base64-encoded string.

Returns

Promise<string>

Since

SDK 2.30.3 Protocol 1.9.0

refresh()

refresh(): Promise<Material>

Re-fetches this material from SketchUp to get its current state (color, texture, alpha may have changed).

Returns

Promise<Material>

toString()

toString(): string

Returns

string

Show Deprecated

Deprecated

export()

export(): Promise<string>

Returns

Promise<string>

Since

SDK 2.12.0 Protocol 1.9.0