> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ploterr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use the block catalog

> Load a free block of furniture, a fixture or equipment from the Floorkit block catalog, and give its source to a session.

The Floorkit block catalog is a free set of blocks: furniture, sanitaryware, kitchen runs, doors, planting, vehicles and data-centre equipment. Each block is one `.op` file with a plan symbol and a 3D body. The blocks are licensed under CC BY 4.0. They need no Floorkit licence key of their own.

## Before you start

You have a building model with a storey `ground`. See [Start a building](https://docs.ploterr.com/floorkit/guides/start-a-building.md). The catalog is on GitHub at [OpenGeometry-io/floorkit-catalog](https://github.com/OpenGeometry-io/floorkit-catalog).

## Find a block

jsDelivr serves the catalog from its release tags. Pin a tag in the address, not a branch:

```text theme={null}
https://cdn.jsdelivr.net/gh/OpenGeometry-io/floorkit-catalog@v0.1.0/
```

| Below the address | What it is |
| - | - |
| `index.json` | All blocks: id, version, name, category, dimensions in metres, licence, path, size and SHA-256 |
| `blocks/<publisher>/<slug>/<version>.op` | One block, for example `blocks/floorkit/bathtub/1.0.0.op` |
| `tools/loader.mjs` | The reference loader |

The id of a block is `<publisher>.<slug>`, for example `floorkit.bathtub`. A released block never changes. A fix is a new version in a new file.

## Load a block

Copy `tools/loader.mjs` into your app. It has no dependencies. It runs in a browser and in Node.js 22.

```js theme={null}
import { openCatalog } from './loader.mjs';

const catalog = await openCatalog({
  baseUrl: 'https://cdn.jsdelivr.net/gh/OpenGeometry-io/floorkit-catalog@v0.1.0/',
});
const bathtub = await catalog.load('floorkit.bathtub', { version: '1.0.0' });
```

* `bathtub.entry` is the entry of the block in `index.json`. `bathtub.text` is the `.op` text.
* `load` checks the size, the SHA-256, the id and the version of the file against `index.json`. It refuses a redirect, a path outside the catalog and a revoked block. Each refusal is a `CatalogError` with a `code`.
* `catalog.list()` gives the entries of all blocks.

`index.json` itself is not signed yet. Without the loader, nothing checks the text that you fetch.

## Give the block source

Floorkit does not download blocks. Give the text in `assetSources` when you open the session. The key is the uri of the block: its path below `blocks/`. Thus `blocks/floorkit/bathtub/1.0.0.op` has the uri `floorkit/bathtub/1.0.0.op`.

```typescript theme={null}
import { BuildingSession, type BuildingModel } from '@opengeometry/floorkit';

/** A block as `catalog.load` returns it. */
export interface CatalogBlock {
  entry: { id: string; version: string; path: string };
  text: string;
}

export function catalogUri(block: CatalogBlock): string {
  return block.entry.path.replace(/^blocks\//, '');
}

export function startWithCatalogBlocks(
  model: BuildingModel,
  blocks: readonly CatalogBlock[],
): BuildingSession {
  const assetSources = Object.fromEntries(blocks.map((block) => [catalogUri(block), block.text]));
  return new BuildingSession(model, { assetSources });
}
```

## Add the block as an asset

`add-asset` adds the definition one time. Then place copies with `add-element`. See [Place furniture](https://docs.ploterr.com/floorkit/guides/place-furniture.md).

```typescript theme={null}
export function addCatalogAsset(
  session: BuildingSession,
  assetId: string,
  block: CatalogBlock,
): void {
  session.apply(
    { kind: 'add-asset', assetId, asset: { kind: 'external-op', uri: catalogUri(block) } },
    session.revision,
  );
}
```

A `ProjectManager` saves the `.op` text of each block in the project file. A saved project opens again without the catalog.

## Make one element

For one element outside a building model, give the text to `OpenElement`. Set up the kernel first.

```typescript theme={null}
import { OpenElement } from '@opengeometry/floorkit';

export function catalogElement(block: CatalogBlock): OpenElement {
  return new OpenElement(block.text);
}
```

## Credit the catalog

The blocks and `index.json` are licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Where you show or ship the blocks, credit the catalog with this text:

```text theme={null}
"floorkit-catalog" by Vishwajeet Mane and floorkit-catalog contributors,
https://github.com/OpenGeometry-io/floorkit-catalog, CC BY 4.0
(https://creativecommons.org/licenses/by/4.0/)
```

The loader, the schema and the other tools are licensed under Apache-2.0.

## Rules

* Pin a release tag in the address. A branch can change, and a tag cannot.
* The uri of a block is its path below `blocks/`. Keep this uri: the project file keys the saved text by it.
* An external asset with no source stops the build with an `asset-source-missing` error that names the uri.

## Next

> **[Place furniture](https://docs.ploterr.com/floorkit/guides/place-furniture.md)**
>
> Place, move, turn and mirror the blocks.

> **[OpenElement API](https://docs.ploterr.com/floorkit/api/architecture/open-element.md)**
>
> See the block definition and its fields.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.