Face

A flat surface bounded by edges, the fundamental geometry for 3D modeling.

Faces are what make SketchUp models appear solid — they define the surfaces that the user sees and paints. Every face has an outer boundary loop of edges and may contain inner loops (holes). Faces also have a normal vector that determines which side is “front” vs. “back” — materials can be applied separately to each side.

You’ll encounter faces when querying geometry, measuring areas, or applying materials. Faces can also have components or images glued to them.

Example

let model = await SketchUpApi.getActiveModel();

// Create a rectangular face.
await model.performOperation(op => {
  op.createFace(model, [
    [0, 0, 0], [100, 0, 0],
    [100, 100, 0], [0, 100, 0],
  ]);
}, 'Create rectangle');

// Query it back and inspect its properties.
let faces = await model.entities.get({
  filterBy: { types: ['Face'] }
});
let face = faces[0];

console.log(face.normal.toArray());
// => [0, 0, -1]
console.log(face.area());
// => 10000 (100 * 100 square inches)
console.log(face.edges.length);
// => 4
console.log(face.outerLoop.length);
// => 4

See

Extends

BaseDrawingElement

Properties

attributes

readonly attributes: Attributes

The attribute dictionaries attached to this element. Attributes store custom key-value metadata that extensions can read and write.

Inherited from

BaseDrawingElement.attributes

backMaterialRef

readonly backMaterialRef: MaterialRef | undefined

A reference to the material applied to the back side of this face, if any. Call Model.findEntity with this ref to fetch the full material object.

backTextureInfo

readonly backTextureInfo: { positioned: boolean; projection: Vector3d | undefined; } | undefined

Texture projection information for the back material. Includes the projection vector and whether the texture has been positioned by the user. Undefined if no textured material is applied to the back.

castsShadows

readonly castsShadows: boolean

Whether this element casts shadows onto other geometry.

Inherited from

BaseDrawingElement.castsShadows

frontTextureInfo

readonly frontTextureInfo: { positioned: boolean; projection: Vector3d | undefined; } | undefined

Texture projection information for the front material. Includes the projection vector and whether the texture has been positioned by the user. Undefined if no textured material is applied to the front.

gluedInstanceCount

readonly gluedInstanceCount: number

How many component instances are glued to this face (e.g. windows or doors that cut openings). When greater than zero, the local area() method may overestimate because it doesn’t subtract the cut openings — use getArea() instead for the true visible area.

Since

SDK 2.25.0

hidden

readonly hidden: boolean

Whether this element is hidden. Hidden elements don’t appear in the viewport unless the user enables “View > Hidden Geometry.”

Inherited from

BaseDrawingElement.hidden

holes

readonly holes: readonly readonly EdgeUse[][]

Inner loops cut out from this face. Each hole is a closed loop of EdgeUse objects representing edges that bound a void.

id

readonly id: number

The persistent ID that uniquely identifies this face.

materialRef

readonly materialRef: MaterialRef | undefined

A reference to the material applied to this element, if any. Call getMaterial() to fetch the full Material object with color and texture data.

Inherited from

BaseDrawingElement.materialRef

outerLoop

readonly outerLoop: readonly EdgeUse[]

The boundary edges of this face, ordered counterclockwise when viewed from the front. Each EdgeUse indicates whether the edge is traversed forward or reversed.

receivesShadows

readonly receivesShadows: boolean

Whether this element receives shadows cast by other geometry.

Inherited from

BaseDrawingElement.receivesShadows

tagRef

readonly tagRef: TagRef | undefined

A reference to the tag (formerly “layer”) assigned to this element. Call getTag() to fetch the full Tag object.

Inherited from

BaseDrawingElement.tagRef

type

readonly type: Face = EntityType.Face

Accessors

boundingBox

Get Signature

get boundingBox(): BoundingBox

The axis-aligned bounding box enclosing this face’s outer loop vertices — useful for quick overlap checks.

Since

SDK 2.25.0

Returns

BoundingBox

closedVertexLoops

Get Signature

get closedVertexLoops(): Vertex[][]

The vertices of this face organized into closed loops. The first loop is the outer boundary, followed by any holes. Each loop’s last vertex matches its first vertex to form a closed polygon.

Returns

Vertex[][]

edges

Get Signature

get edges(): Edge[]

All edges bounding this face, including both the outer loop and any holes. The edges are in the order they appear in the loops.

Returns

Edge[]

normal

Get Signature

get normal(): Vector3d

A unit vector pointing outward from the front side of this face. Use it to determine which way the surface is facing.

Since

SDK 2.25.0

Returns

Vector3d

plane

Get Signature

get plane(): Plane

The infinite plane this face lies on, computed from the outer loop vertices. Use plane.normal for the face direction or plane.distance(point) to measure how far a point is from the surface.

Since

SDK 2.25.0

Returns

Plane

sketchupId

Get Signature

get sketchupId(): SketchupId

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

Returns

SketchupId

Overrides

BaseDrawingElement.sketchupId

typeName

Get Signature

get typeName(): string

Returns a named variant of the type field.

Since

SDK 2.35.0

Returns

string

Methods

area()

area(transformLike?): number

Calculates the face area in square inches from the local geometry snapshot. Does not subtract cut openings from glued instances — if gluedInstanceCount > 0, use getArea instead for the true visible area.

Parameters

Parameter	Type	Description
`transformLike?`	`TransformationLike`	optional transformation to apply

Returns

number

area in square inches

Since

SDK 2.25.0

classifyPoint()

classifyPoint(point): FacePointClassification

Classifies where a point lies relative to this face — on the plane, inside the boundary, on an edge, at a vertex, or outside. Useful for hit testing, proximity checks, or determining if a point is within a face’s bounds.

Parameters

Parameter	Type	Description
`point`	`Point3Like`	The 3D point to classify.

Returns

FacePointClassification

A classification enum indicating the point’s relationship to the face.

Since

SDK 2.25.0

coplanarWith()

coplanarWith(other): boolean

Checks whether another face lies in the same plane as this one. Coplanar faces share the same infinite plane even if they don’t overlap. Useful for detecting faces that could be merged or for analyzing geometry alignment.

Parameters

Parameter	Type	Description
`other`	`Face`	The face to compare against.

Returns

boolean

True if both faces lie in the same plane.

Since

SDK 2.25.0

getAllConnected()

getAllConnected<Filter>(options?): Promise<EntityTypeForFilter<Filter, DrawingElement>[]>

Traverses the edge graph to find all geometry topologically connected to this face through shared edges — like flood-filling across the mesh. Returns faces, edges, and other drawing elements in the connected component (includes this face itself). Optionally filter by entity type.

Type Parameters

Type Parameter
`Filter` extends `EntityFilter`

Parameters

Parameter	Type	Description
`options?`	`EntityQuery`<`Filter`>	optional entity type filter

Returns

Promise<EntityTypeForFilter<Filter, DrawingElement>[]>

Since

SDK 2.25.0 Protocol 1.22.0

getArea()

getArea(transformLike?): Promise<number>

Fetches the area of this face from SketchUp, accounting for glued instances that cut openings (like windows or doors). Unlike area, which calculates from the geometry snapshot, this queries SketchUp for the rendered area including all cut-opening effects.

Parameters

Parameter	Type	Description
`transformLike?`	`TransformationLike`	Optional transformation to apply before measuring.

Returns

Promise<number>

The area in square inches.

Since

SDK 2.25.0 Protocol 1.22.0

getBounds()

getBounds(): Promise<BoundingBox>

Fetches the axis-aligned bounding box for this element from SketchUp.

Returns

Promise<BoundingBox>

Example

let model = await SketchUpApi.getActiveModel();
let all = await model.entities.get();
let element = all[0];
let box = await element.getBounds();
console.log(box.min.x, box.min.y, box.min.z);
console.log(box.max.x, box.max.y, box.max.z);

Since

SDK 2.30.0

Inherited from

BaseDrawingElement.getBounds

getGluedInstances()

getGluedInstances<Filter>(options?): Promise<EntityTypeForFilter<Filter, CanBeGlued>[]>

Fetches component instances, groups, and images that are glued (attached) to this face’s surface. Glued instances move and rotate with the face — common for windows glued to walls or decals on surfaces.

Type Parameters

Type Parameter	Default type
`Filter` extends `EntityFilter`	`EntityFilter`

Parameters

Parameter	Type	Description
`options?`	`SketchupEntityFilter` \| `EntityQuery`<`Filter`>	optional entity type filter

Returns

Promise<EntityTypeForFilter<Filter, CanBeGlued>[]>

Since

SDK 2.21.0 Protocol 1.18.0

getMaterial()

getMaterial(): Promise<Material | undefined>

Fetches the material applied to this element. Returns undefined if the element uses the default material.

Returns

Promise<Material | undefined>

Example

let model = await SketchUpApi.getActiveModel();
let all = await model.entities.get();
let element = all[0];
let mat = await element.getMaterial();
if (mat) {
  console.log(mat.name, mat.color.toHex());
}

Since

SDK 2.30.0

Inherited from

BaseDrawingElement.getMaterial

getTag()

getTag(): Promise<Tag | undefined>

Fetches the tag assigned to this element. Most elements have a tag — even those on the default “Untagged” tag. Returns undefined only if the tag reference is missing.

Returns

Promise<Tag | undefined>

Example

let model = await SketchUpApi.getActiveModel();
let all = await model.entities.get();
let element = all[0];
let tag = await element.getTag();
if (tag) {
  console.log(tag.name);
}

Since

SDK 2.30.0

Inherited from

BaseDrawingElement.getTag

getUVs()

getUVs(uvRequest): Promise<UVResponse>

Computes UV texture coordinates for 3D points on this face. UVs map a 2D texture image onto the face’s 3D surface. You can request coordinates for points on the front side, back side, or both.

Parameters

Parameter	Type	Description
`uvRequest`	`UVRequest`	Object specifying `front` and/or `back` arrays of 3D points.

Returns

Promise<UVResponse>

UV coordinates for each requested point.

Since

SDK 2.25.0 Protocol 1.22.0

getUVTiles()

getUVTiles(uvRequest): Promise<UVTileResponse>

Computes UV tile indices for 3D points on this face. Tiles are discrete regions of a repeating texture — this method returns which tile each point falls into, useful for texture atlases or tiled material effects.

Parameters

Parameter	Type	Description
`uvRequest`	`UVRequest`	Object specifying `front` and/or `back` arrays of 3D points.

Returns

Promise<UVTileResponse>

Tile indices for each requested point.

Since

SDK 2.25.0 Protocol 1.22.0

refresh()

refresh(): Promise<Face>

Re-fetches this face from SketchUp to get its current state. Because Face is a snapshot, it can become stale if the model changes. Call refresh() to get an up-to-date copy.

Returns

Promise<Face>

A new Face reflecting the current model state. Throws if the face has been deleted.

Example

let model = await SketchUpApi.getActiveModel();
let faces = await model.entities.get({
  filterBy: { types: ['Face'] },
});
// Then later if you suspect the user changed it...
let fresh = await faces[0].refresh();
console.log(fresh.area());

toString()

toString(): string

Returns a string representation of an object.

Returns

string

Show Deprecated

Deprecated

backMaterialId

readonly backMaterialId: number | undefined

The persistent id of the material

materialId

readonly materialId: number | undefined

Inherited from

BaseDrawingElement.materialId

tagId

readonly tagId: number | undefined

Inherited from

BaseDrawingElement.tagId

bounds

Get Signature

get bounds(): Promise<BoundingBox>

Returns

Promise<BoundingBox>

Inherited from

BaseDrawingElement.bounds