CAD Blocks

Use viewer.blocks to request lightweight CAD block lists, lazily load block details or attributes, listen for block snapshots, and update block visibility.

Block commands are available after the viewer is mounted, Canvas is ready, and a CAD document is open.

import { createViewer } from "@rasterex/viewer";

const viewer = createViewer({
  container: "#viewer"
});

await viewer.mount();
await viewer.ready();

await viewer.documents.open({
  url: "https://files.example.com/floor-plan.dwg",
  displayName: "floor-plan.dwg"
});

Use getBlocks() for lists, tables, and sidebar UI. It returns lightweight block rows.

• getBlocks() sends getBlocks and waits for blocksSnapshot.

const snapshot = await viewer.blocks.getBlocks();

for (const block of snapshot.blocks) {
  console.log(block.index, block.name, block.visible, block.hasAttribute);
}

Use getBlockDetails(...) when a user selects block rows and you need geometry, insert data, bounds, or attributes.

• Request several blocks with indexes:
• The shorter alias getDetails(...) is also supported:

const details = await viewer.blocks.getBlockDetails({
  indexes: [3, 4, 5]
});

// Shorter alias:
await viewer.blocks.getDetails({ index: 3 });

const details = await viewer.blocks.getBlockDetails({
  index: 3
});

console.log(details.blocks[0]?.details?.bounds?.width);
console.log(details.blocks[0]?.attributes);

Use getBlockAttributes(...) when you only need attributes for selected blocks.

• Shorter alias getAttributes(...) is also supported:

await viewer.blocks.getAttributes({ index: 3 });

const result = await viewer.blocks.getBlockAttributes({
  index: 3
});

console.log(result.blocks[0]?.attributes ?? []);

Use indexes or names returned by getBlocks() to toggle visibility.

• setBlockVisibility(...) sends setBlockVisibility and returns void.
• Shorter alias setVisibility(...) is also supported:

viewer.blocks.setVisibility({
  all: true,
  visible: true
});

viewer.blocks.setBlockVisibility({
  index: 3,
  visible: false
});

Use exactly one selector per visibility call:

• index: One block by index.
• indexes: Multiple blocks by index.
• name: One block by name.
• names: Multiple blocks by name.
• all: Every block.

viewer.blocks.setBlockVisibility({ index: 3, visible: false });
viewer.blocks.setBlockVisibility({ indexes: [4, 7], visible: false });
viewer.blocks.setBlockVisibility({ name: "DOOR_TAG", visible: true });
viewer.blocks.setBlockVisibility({ names: ["DOOR_TAG", "WINDOW_TAG"], visible: true });
viewer.blocks.setBlockVisibility({ all: true, visible: true });

Subscribe to real-time CAD block snapshots and events:

const cleanups = [
  viewer.blocks.on("snapshot", (snapshot) => {
    console.log(snapshot.blocks);
  }),
  viewer.blocks.on("detailsSnapshot", (snapshot) => {
    console.log(snapshot.blocks[0]?.details);
  }),
  viewer.blocks.on("attributesSnapshot", (snapshot) => {
    console.log(snapshot.blocks[0]?.attributes);
  })
];

// Clean up listeners:
for (const cleanup of cleanups) cleanup();

Block list and block detail type declarations:

type BlockItem = {
  index?: number;
  name?: string;
  visible: boolean;
  selected?: boolean;
  hasAttribute?: boolean;
  [key: string]: unknown;
};

type BlocksSnapshot = {
  requestId?: string;
  fileId?: string;
  fileIndex?: number;
  fileName?: string;
  blocks: BlockItem[];
  [key: string]: unknown;
};

type BlockAttribute = {
  name: string;
  value: unknown;
  blockref?: number;
  [key: string]: unknown;
};

type BlockBounds = {
  minX?: number;
  minY?: number;
  maxX?: number;
  maxY?: number;
  width?: number;
  height?: number;
  area?: number;
  [key: string]: unknown;
};

type BlockInsertDetails = {
  blockhandleLow?: number;
  blockhandleHigh?: number;
  insertX?: number;
  insertY?: number;
  insertZ?: number;
  insertRot?: number;
  insertscaleX?: number;
  insertscaleY?: number;
  insertscaleZ?: number;
  blockref?: number;
  MinX?: number;
  MinY?: number;
  MaxX?: number;
  MaxY?: number;
  type?: string;
  [key: string]: unknown;
};

type BlockDetails = {
  index?: number;
  name?: string;
  state?: number;
  defaultstate?: number;
  defaultcolor?: string | null;
  color?: string | null;
  fillstyle?: string | null;
  defaultfillstyle?: string | null;
  overridecolor?: boolean;
  overridefill?: boolean;
  hatchstyle?: string | null;
  selected?: boolean;
  listed?: boolean;
  insert?: BlockInsertDetails;
  drawn?: boolean;
  mouseon?: boolean;
  hasAttribute?: boolean;
  fold?: number;
  bounds?: BlockBounds;
  [key: string]: unknown;
};

type BlockDetailsItem = {
  index?: number;
  name?: string;
  visible?: boolean;
  selected?: boolean;
  hasAttribute?: boolean;
  details?: BlockDetails;
  attributes?: BlockAttribute[];
  [key: string]: unknown;
};

type BlockDetailsSnapshot = {
  requestId?: string;
  fileId?: string;
  fileIndex?: number;
  fileName?: string;
  blocks: BlockDetailsItem[];
  [key: string]: unknown;
};

type BlockAttributesSnapshot = BlockDetailsSnapshot;

Method payload option structures:

type GetBlocksOptions = {
  requestId?: string;
  timeoutMs?: number;
};

type GetBlockDetailsOptions = {
  requestId?: string;
  index?: number;
  indexes?: number[];
  timeoutMs?: number;
};

type GetBlockAttributesOptions = GetBlockDetailsOptions;

type SetBlockVisibilityOptions = {
  requestId?: string;
  index?: number;
  indexes?: number[];
  name?: string;
  names?: string[];
  all?: boolean;
  visible: boolean;
};

All exported typings for CAD block integrations:

import type {
  BlockAttribute,
  BlockAttributesSnapshot,
  BlockBounds,
  BlockDetails,
  BlockDetailsItem,
  BlockDetailsSnapshot,
  BlockInsertDetails,
  BlockItem,
  BlocksApiOptions,
  BlocksEventHandler,
  BlocksEventMap,
  BlocksEventName,
  BlocksEventUnsubscribe,
  BlocksSnapshot,
  GetBlockAttributesOptions,
  GetBlockDetailsOptions,
  GetBlocksOptions,
  SetBlockVisibilityOptions
} from "@rasterex/viewer";

Validation constraints apply to block method requests:

• getBlockDetails(...) and getBlockAttributes(...) require exactly one selector: index or indexes.
• index must be a non-negative integer.
• indexes must be a non-empty array of non-negative integers.
• setBlockVisibility(...) requires visible as a boolean and exactly one selector: index, indexes, name, names, or all.
• name must not be empty.
• names must be a non-empty array of non-empty strings.

Complete implementation details for Vanilla HTML/JS environments:

<div id="viewer" style="height: 640px"></div>
<button type="button" id="load-blocks">Load Blocks</button>
<button type="button" id="load-details">Load First Details</button>
<button type="button" id="hide-first-block">Hide First Block</button>
<pre id="status"></pre>

Broker message mapping for CAD block APIs:

• viewer.blocks.getBlocks(...) maps to getBlocks.
• viewer.blocks.getBlockDetails(...) maps to getBlockDetails.
• viewer.blocks.getDetails(...) maps to getBlockDetails.
• viewer.blocks.getBlockAttributes(...) maps to getBlockAttributes.
• viewer.blocks.getAttributes(...) maps to getBlockAttributes.
• viewer.blocks.setBlockVisibility(...) maps to setBlockVisibility.
• viewer.blocks.setVisibility(...) maps to setBlockVisibility.
• viewer.blocks.on("snapshot", ...) listens to blocksSnapshot.
• viewer.blocks.on("detailsSnapshot", ...) listens to blockDetailsSnapshot.
• viewer.blocks.on("attributesSnapshot", ...) listens to blockAttributesSnapshot.

Use the related pages below when you need the matching layer workflow or the full payload reference.

• Layers: Layers
• Technical Reference: API References
• CAD Overview: Overview