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

> Put a beam between two points on a storey.

A beam is a straight member between two points. You give its two ends and its section. The ends can be at different heights, so a beam can slope.

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

## Before you start

You have a session from [Start a building](https://docs.ploterr.com/floorkit/guides/start-a-building.md).

## Write the beams

A beam end is `[x, y, z]` in metres. `x` and `z` are the plan position. `y` is the height above the storey, not a world height. These two beams run along the two sides of a 6 by 4 metre bay, 2.85 metres above the storey. Each has a section of 0.2 by 0.4 metres.

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

export const bayBeams: BmBeam[] = [
  {
    id: 'beam-north',
    shape: BeamShape.RECTANGULAR,
    start: [0, 2.85, 0],
    end: [6, 2.85, 0],
    width: 0.2,
    depth: 0.4,
  },
  {
    id: 'beam-south',
    shape: BeamShape.RECTANGULAR,
    start: [0, 2.85, 4],
    end: [6, 2.85, 4],
    width: 0.2,
    depth: 0.4,
  },
];
```

## Add them to the storey

A beam is an entry in the `beams` list of its storey. This batch adds the two beams in one step.

```typescript theme={null}
export function addBeams(session: BuildingSession): void {
  session.apply(
    {
      kind: 'batch',
      commands: bayBeams.map((beam) => ({
        kind: 'add-element' as const,
        buildingId: 'building',
        storeyId: 'ground',
        list: 'beams' as const,
        element: beam,
      })),
    },
    session.revision,
  );
}
```

The `add-element` command rejects an id that the list has. One undo takes the two beams away.

## Change a beam

Send `replace-element` with the full new beam. The id stays the same. This example makes a beam deeper.

```typescript theme={null}
export function deepenBeam(session: BuildingSession, beam: BmBeam): void {
  session.apply(
    {
      kind: 'replace-element',
      buildingId: 'building',
      storeyId: 'ground',
      list: 'beams',
      elementId: beam.id,
      element: { ...beam, depth: 0.5 },
    },
    session.revision,
  );
}
```

In the plan editor and the 3D editor, the panel of a selected beam shows its shape, its size, its two ends, its material and its colour. Each change saves one `replace-element`. The panel shows the ends as world points and saves `y` above the storey.

## Draw beams in the plan editor

`startBeamDrawing` lets the user draw beams with two clicks each. Each beam is one `add-element` and one undo step. The next beam starts where the last one ended. Escape or Enter ends the chain, and the promise gives the ids of the saved beams.

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

export async function drawBeams(plan: ManagedPlanEditor): Promise<string[]> {
  return plan.startBeamDrawing({ axisHeight: 2.85, width: 0.2, depth: 0.4 });
}
```

Every end is at `axisHeight` above the storey. A click snaps to a column center, then to a wall axis. Shift locks the axis, and Backspace removes the last point. A site plan has no storey, so it refuses the drawing.

## Move, reshape and delete

A selected beam has these grips. One drag is one step. The 3D editor has the move and turn grips; the end grips are in the plan editor only.

| Grip | What it does |
| - | - |
| Move | Moves the two ends in plan. Their heights stay. |
| Turn | Turns the two ends around the middle of the beam. Their heights stay. |
| `end:start` and `end:end` | Moves one end in plan. Its height stays. |

To move a beam in code, see [Move or turn a beam](https://docs.ploterr.com/floorkit/guides/move-and-reshape.md#move-or-turn-a-beam). To delete a beam, select it and push the Delete key, or send `remove-element` with its id. One undo brings it back.

## Sections

| `shape` | You give |
| - | - |
| `BeamShape.RECTANGULAR` | `width` (across) and `depth` (up) |
| `BeamShape.CIRCULAR` | `radius` |
| `BeamShape.CUSTOM` | `customProfile`, your own outline. Only its outer ring is used |

## Rules

* `y` of `start` and `end` is the height above the storey elevation. A beam moves with its storey.
* The axis goes through the centre of the section. The two ends must be different points.
* A section or an elevation draws every beam: rectangular, round, and custom with a convex or a non-convex outline, level or sloped. To cut a sloped round beam, or a level one at a slant, a section needs an OpenGeometry kernel that cuts a tilted cylinder. With an older kernel, that section stops with an error that names the beam.
* A plan draws a beam in one of three states: cut by the plan cut, below it, or above it, dashed.
* A beam is geometry. Floorkit does not calculate loads.

## Next

> **[Add a column](https://docs.ploterr.com/floorkit/guides/add-a-column.md)**
>
> Put a column under each end.

> **[Beam API](https://docs.ploterr.com/floorkit/api/architecture/beam.md)**
>
> See each option of a beam.


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