Web Loom Component

A web component for creating and visualizing weaving patterns in the browser. Design and display weaving drafts with customizable threading, treadling, and tie-up patterns and embed them easily on your web page!

Demo

Try the live demo here: https://pcsteppan.github.io/web-loom/

Installation

Using CDN (Recommended)

The easiest way to use this component is via CDN:

<script type="module" src="https://cdn.jsdelivr.net/npm/web-loom/dist/cdn/main.js"></script>
<web-loom></web-loom>

Using npm

npm install web-loom

Then import it in your JavaScript:

import 'web-loom';

Basic Usage

Add the web-loom component to your HTML:

<web-loom></web-loom>

Properties

The web-loom component supports the following properties:

| Property | Type | Default | Description | |----------|------|---------|-------------| | threading | Array | [1, 2, 3, 4, 1, 2, 3, 4] | Defines the threading pattern | | treadling | Array | [1, 2, 3, 4, 1, 2, 3, 4] | Defines the treadling pattern | | tieup | Array | [[1, 0, 0, 1], [0, 0, 1, 1], [0, 1, 1, 0], [1, 1, 0, 0]] | Defines the tie-up matrix | | auto_balance | Boolean | false | When true, balances threading and treadling lengths | | min_size | Number | 64 | Minimum size for the pattern | | scale | Number | 1 | Scaling factor for the pattern | | mode | String | 'editing_mode' | Display mode: 'editing_mode' or 'presentation_mode' | | dithering_mode | String | 'none' | Dithering mode: 'none', 'bayer 4x4', or 'noise' | | disable_shading | Boolean | false | When true, disables thread shading effects | | invert | Boolean | false | When true, inverts the pattern colors | | warp_color | Array | [1, 1, 1] | RGB color for warp threads (values 0-1) | | weft_color | Array | [0, 0, 0] | RGB color for weft threads (values 0-1) | | sizing_mode | String | 'proportional' | Sizing behavior: 'proportional', 'aspect-ratio', or 'fit-container' | | aspect_ratio | String | undefined | Aspect ratio when sizing_mode is 'aspect-ratio' (e.g., '1/1', '16/9') | | disable_save_and_load | Boolean | false | When true, disables save and load functionality |

Sizing Modes

The sizing_mode property controls how the web-loom component determines its canvas dimensions:

'proportional' (Default)

The canvas size is calculated proportionally based on the threading and treadling pattern lengths. The aspect ratio automatically adjusts to match the pattern proportions.

<web-loom sizing_mode="proportional"></web-loom>

'aspect-ratio'

The canvas maintains a fixed aspect ratio specified by the aspect_ratio property. This is useful when you need consistent dimensions regardless of pattern complexity.

<web-loom sizing_mode="aspect-ratio" aspect_ratio="1/1"></web-loom>
<web-loom sizing_mode="aspect-ratio" aspect_ratio="16/9"></web-loom>

'fit-container'

The canvas automatically fits to fill its parent container. This is ideal for responsive layouts where the loom should adapt to available space.

<div style="width: 500px; height: 400px;">
  <web-loom sizing_mode="fit-container"></web-loom>
</div>

CSS Custom Properties

You can customize the appearance using these CSS variables:

web-loom {
  --font-family: 'Courier', monospace;
  --web-loom-text-color: #000;
  --primary-ui-color: #000;
  --primary-bg-color: #aaa;
  --web-loom-font-size: 1rem;
}

Methods

| Method | Description | |--------|-------------| | save() | Saves the current pattern as a JSON file | | exportImage() | Exports the current pattern as a PNG image | | load(data) | Loads a pattern from a JSON string |

Events

| Event | Description | |-------|-------------| | draftChange | Fired when threading, treadling, or tie-up changes | | stateChange | Fired when any serializable property changes | | canvasResize | Fired when the canvas is resized |

Migration from v0.2.x

If you're upgrading from a previous version, the sizing API has been simplified:

Old API (deprecated):

<web-loom dynamic_sizing="true" fixed_aspect_ratio="1/1" fit_container="false"></web-loom>

New API:

<web-loom sizing_mode="aspect-ratio" aspect_ratio="1/1"></web-loom>

Migration mapping:

• dynamic_sizing="true" → sizing_mode="proportional"
• fixed_aspect_ratio="X/Y" → sizing_mode="aspect-ratio" aspect_ratio="X/Y"
• fit_container="true" → sizing_mode="fit-container"

License

MIT