> ## 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.

# Add a railing

> Put a balustrade along a balcony edge or up a stair, with balusters or glass panels.

A railing is a top rail along a path. Under the rail it has square balusters, or glass panels when you give it a `panel`.

[Live example](https://floorkit-examples.ploterr.com/floorkit/guides/add-a-railing?embed=1)

## Before you start

You have a session from [Start a building](https://docs.ploterr.com/floorkit/guides/start-a-building.md) with a second storey `level-1` at elevation 4.5. See [Add a storey](https://docs.ploterr.com/floorkit/guides/add-a-storey.md). The stair rail below also needs the stair `main-stair` from [Add a stair](https://docs.ploterr.com/floorkit/guides/add-a-stair.md) on the storey of the rail.

## Write the railing

The points of `path` are `[x, y, z]` in world coordinates, not relative to the storey. This balcony railing stands on a storey at elevation 4.5, so every point has `y` 4.5.

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

export const balcony: BmRailing = {
  id: 'balcony-rail',
  path: [
    [0, 4.5, -1],
    [6, 4.5, -1],
    [6, 4.5, 2],
  ],
  height: 1.1,
};
```

A point below the storey's elevation, or above the elevation plus the height, validates with a `path-outside-storey` warning. A `y` written relative to the storey is the usual cause.

## Add it to the storey

```typescript theme={null}
export function addRailing(session: BuildingSession): void {
  session.apply(
    {
      kind: 'add-element',
      buildingId: 'building',
      storeyId: 'level-1',
      list: 'railings',
      element: balcony,
    },
    session.revision,
  );
}
```

## Curve the path

`arcs` bends a segment of the path: `arcs[i]` is `{ through }` for segment `i`, a point the arc passes through, or `null` for a straight segment. `cornerRadii` rounds a corner: `cornerRadii[i]` is the radius at the inner point `path[i + 1]`, or `null` for a sharp corner. Either takes a level path, with `through` at the same `y`.

```typescript theme={null}
export function replaceBalcony(session: BuildingSession, element: BmRailing): void {
  session.apply(
    {
      kind: 'replace-element',
      buildingId: 'building',
      storeyId: 'level-1',
      list: 'railings',
      elementId: balcony.id,
      element,
    },
    session.revision,
  );
}

export function curvePath(session: BuildingSession): void {
  replaceBalcony(session, { ...balcony, arcs: [null, { through: [7.5, 4.5, 0.5] }] });
}

export function roundCorner(session: BuildingSession): void {
  replaceBalcony(session, { ...balcony, cornerRadii: [1] });
}

export function straightAgain(session: BuildingSession): void {
  replaceBalcony(session, balcony);
}
```

The top rail sweeps the arc as one continuous rail. On a path with sloped segments elsewhere, the curved rail is built as short straight pieces of at most 5° of arc each, not as a true arc. Balusters stand at their spacing measured along the arc, not along its chord, so a curved segment carries more of them than a straight one between the same two points. The plan draws the arc, and the IFC export writes an `IfcRailing` whose body is swept along it.

A corner radius may be at most what the two segments beside it leave, and a corner beside an arc segment takes none. Both are refused at validation with `corner-radius-too-big` and `corner-radius-arc-edge`.

## Glass panels

Give the railing a `panel` and it builds glass in place of the balusters. Each segment of the path is split into equal bays no wider than 1.2 m, with one pane in each bay. Along an arc the glass is faceted: the arc is split into straight panes no wider than 1.2 m, each standing on its chord.

```typescript theme={null}
export const glassBalcony: BmRailing = {
  ...balcony,
  id: 'glass-rail',
  panel: { thickness: 0.012, material: 'laminated 8.8', fixing: 'spigots' },
};
```

| Field | Meaning | Default |
| - | - | - |
| `thickness` | Glass thickness in metres | `0.012` |
| `material` | The name of the glass, as a schedule lists it | none |
| `fixing` | `posts`, `spigots` or `clamped` | `posts` |

* `posts`: a post at each end of each bay, with the glass between them.
* `spigots`: two spigots under each pane, which stands on them.
* `clamped`: two clamps on the lower edge of each pane.

A panel takes only these three fields. Any other key is refused with `unknown-field`.

Sections and elevations draw the panes as glass: they hide nothing behind them. The plan draws the railing as its path, arcs included, with or without glass. A plan view with `railingLines: 'double'` draws each railing as two lines, the two faces of its top rail, one `topRail.width` apart. The lines meet at the corners, an arc draws as two arcs, and a line across the rail closes each end of a path that is not closed.

## On a stair

A railing with `host` in place of `path` follows one side of a stair of the same storey.

```typescript theme={null}
export const stairRail: BmRailing = {
  id: 'stair-rail',
  host: { stairId: 'main-stair', side: 'left', inset: 0.05 },
  height: 0.9,
};
```

The plan of the storey above draws the part of the rail above the lower plan's cut, as it draws the stair: thin, and not selectable there.

## Edit it

In the plan and in the 3D editor, a free railing has a grip on each point of its path. A drag saves one `replace-element` with the new path in whole millimetres. The heights of the points stay. A hosted railing has no grips: it follows its stair.

`replaceFields` changes the fields an inspector shows, by their schema paths:

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

export function useClamps(manager: ProjectManager): void {
  manager.replaceFields('glass-rail', { 'panel.fixing': 'clamped', 'panel.thickness': 0.015 });
}
```

`GUIEditor.startRailingDrawing(storeyId, options)` draws a railing in the 3D editor with the keys of the wall draft. Enter saves it; a click on the first point closes it.


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