# How Column Fit Layout Works in Archify: Fixed vs Spread Explained

> Learn how Archify's column fit layout uses meta.column_fit for fixed vs spread participant boxes. Optimize canvas space and element display with Archify.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-15

---

**Archify's column fit layout uses `meta.column_fit` to control whether participant boxes stay at fixed widths or expand to fill available canvas space.**

The Archify sequence diagram renderer positions participants in horizontal lanes with dimensions that depend on the `column_fit` setting in a diagram's JSON metadata. This article explains how the **fixed** (default) and **spread** modes differ, when to use each, and how they're implemented in the source code.

## Fixed Mode: Stable Historical Coordinates

The **fixed** mode is the default behavior. Participant boxes are rendered at a constant **86 px** width with a constant **108 px** column gap. This layout **ignores the canvas width** entirely—adding extra space to the `viewBox` simply leaves empty space on the right side of the diagram.

In `archify/renderers/sequence/render-sequence.mjs`, the renderer resolves the mode with a fallback to fixed:

```javascript
// archify/renderers/sequence/render-sequence.mjs
const columnFit = sequence.meta?.column_fit === 'spread' ? 'spread' : 'fixed';

```

*Source: [render-sequence.mjs, lines 25-30](https://github.com/tt-a1i/archify/blob/main/archify/renderers/sequence/render-sequence.mjs#L25-L30)*

**When to use fixed mode:**

- Preserving historical coordinates in existing diagrams
- Maintaining predictable, pixel-perfect layouts
- Diagrams already designed for the 86 px / 108 px spacing

## Spread Mode: Responsive Canvas Filling

The **spread** mode derives box width and column gap from the canvas (`viewBox`) width. Boxes expand up to **190 px** and gaps grow proportionally to fill horizontal space without changing participant order or message semantics.

The schema documents this behavior in [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json):

```json
"column_fit": {
  "description": "Horizontal participant layout. Omit this field or use fixed for the stable 86px boxes and 108px gap. Use spread when a wide viewBox would leave unused horizontal space or meaningful participant labels do not fit the fixed boxes; spread derives wider boxes and gaps from the viewBox without changing participant order or message semantics.",
  "enum": ["fixed", "spread"]
}

```

*Source: [sequence.schema.json, lines 58-61](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json#L58-L61)*

**When to use spread mode:**

- Wide `viewBox` would otherwise leave unused space
- Participant labels exceed the fixed 86 px box width
- You want the diagram to visually fill the available canvas

## Code Examples: Column Fit in Practice

### Default Fixed Behavior

```javascript
// Fixed column fit (default behavior)
{
  "meta": { "title": "Demo", "viewBox": [1320, 620] },
  "participants": [
    { "id": "a", "type": "frontend", "label": "A" },
    { "id": "b", "type": "backend",  "label": "B" }
  ],
  "messages": [{ "from": "a", "to": "b", "y": 200, "label": "request" }]
}

```

**Result:** Participant boxes are 86 px wide, column gap = 108 px regardless of canvas width.

### Spread Mode on Wide Canvas

```javascript
// Spread column fit for full-width diagrams
{
  "meta": { "title": "Demo", "viewBox": [1320, 620], "column_fit": "spread" },
  "participants": [
    { "id": "a", "type": "frontend", "label": "A" },
    { "id": "b", "type": "backend",  "label": "B" }
  ],
  "messages": [{ "from": "a", "to": "b", "y": 200, "label": "request" }]
}

```

**Result:** Boxes widen (up to 190 px) and gaps expand to fill the viewBox width.

### Handling Long Labels

```javascript
// Spread mode accommodates lengthy participant names
{
  "meta": { "title": "Demo", "viewBox": [1320, 620], "column_fit": "spread" },
  "participants": [
    { "id": "a", "type": "frontend", "label": "A" },
    { "id": "b", "type": "backend",  "label": "A Very Long Participant Name That Exceeds 86px" }
  ],
  "messages": [{ "from": "a", "to": "b", "y": 200, "label": "request" }]
}

```

**Result:** The long label renders properly because spread mode enlarges the participant box. The same diagram would fail or truncate in fixed mode.

## Implementation and Verification

The renderer's README provides user-facing documentation:

> "Sequence diagrams use `meta.column_fit: "fixed"` by default so existing documents keep their historical coordinates. Use `"spread"` when a wide viewBox would otherwise leave empty space on the right or when meaningful participant labels do not fit the fixed 86px boxes."

*Source: [README.md, lines 73-80](https://github.com/tt-a1i/archify/blob/main/archify/renderers/sequence/README.md#L73-L80)*

The Archify test suite in `archify/test/sequence-column-fit.test.mjs` validates these behaviors:

- **Fixed** maintains 108 px gap regardless of canvas width
- **Spread** widens boxes, increases gaps, respects side margins, and stays within viewBox
- **Opt-in behavior:** omitting `column_fit` yields identical output to explicit `"fixed"`

*Source: [sequence-column-fit.test.mjs, lines 68-84](https://github.com/tt-a1i/archify/blob/main/archify/test/sequence-column-fit.test.mjs#L68-L84)*

## Key Source Files

| File | Purpose |
|------|---------|
| `archify/renderers/sequence/render-sequence.mjs` | Core renderer; determines `columnFit` and computes dimensions |
| [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) | JSON Schema definition for `column_fit` property |
| [`archify/renderers/sequence/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/sequence/README.md) | User documentation for column fit options |
| `archify/test/sequence-column-fit.test.mjs` | Automated tests verifying fixed and spread behavior |

## Summary

- **Fixed mode** provides stable 86 px boxes and 108 px gaps—ideal for existing diagrams and pixel-precise layouts
- **Spread mode** scales boxes up to 190 px and expands gaps to fill the viewBox—use for wide canvases or long labels
- Set `meta.column_fit` to `"spread"` to enable responsive layout; omit or set to `"fixed"` for default behavior
- The renderer in `render-sequence.mjs` uses a simple ternary to resolve the mode at lines 25-30

## Frequently Asked Questions

### What is the default column fit mode in Archify?

**Fixed mode is the default.** If you omit `column_fit` from your diagram's metadata or set it to any value other than `"spread"`, Archify uses fixed dimensions: 86 px participant boxes with 108 px column gaps. This default preserves backward compatibility with existing diagrams.

### How do I switch to spread mode in my Archify diagram?

Add `"column_fit": "spread"` to your diagram's `meta` object. The spread mode automatically calculates box widths and gaps based on your `viewBox` width, allowing boxes to grow up to 190 px and gaps to expand proportionally.

### Why would fixed column fit leave empty space on the right?

Fixed mode uses constant dimensions regardless of canvas size. If your `viewBox` width exceeds what the fixed boxes and gaps require, the remaining space stays empty. This is intentional—it ensures historical diagrams maintain their exact coordinates rather than stretching unexpectedly.

### Can spread mode handle participant labels longer than 86 characters?

**Yes, spread mode accommodates longer labels.** While the limit is 190 px (not characters), spread mode's elastic box sizing provides significantly more room than fixed mode's rigid 86 px constraint. For extremely long labels, consider abbreviations or multi-line formatting regardless of mode.