Menu
Create and edit jay-html template files with data binding, headless components, conditional rendering, loops, and styling. Also covers directory-based routing in jay-stack. Use when creating pages, editing templates, or setting up routes.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Main entry point for AI agents building jay-stack applications. Use when creating pages, working with headless components, or generating jay-html from contracts. Covers the full workflow from reading contracts to producing valid jay-html pages.
Use jay-stack CLI commands for setup, discovery and validation. Covers jay-stack setup (plugin config and references), jay-stack params (discover URL param values for SSG), jay-stack action (run plugin actions), and jay-stack validate (check jay-html and contract files). Use when discovering data, validating files, or running plugin actions.
Read plugin.yaml files and materialized contracts from the agent-kit to understand available components, data shapes, and rendering phases. Use when you need to discover what plugins/contracts exist or understand a contract's tags before creating jay-html.
| name | jay-html-authoring |
| description | Create and edit jay-html template files with data binding, headless components, conditional rendering, loops, and styling. Also covers directory-based routing in jay-stack. Use when creating pages, editing templates, or setting up routes. |
A .jay-html file is standard HTML with jay-specific extensions for data binding, conditions, loops, and headless component integration.
<html>
<head>
<!-- Page contract (optional) -->
<script type="application/jay-data" contract="./page.jay-contract"></script>
<!-- Headless component imports -->
<script type="application/jay-headless" plugin="..." contract="..." key="..."></script>
<!-- Styles -->
<style>
/* inline CSS */
</style>
<link rel="stylesheet" href="../../styles/theme.css" />
</head>
<body>
<!-- Template with data bindings -->
<h1>{title}</h1>
</body>
</html>
Use {expression} to bind contract data:
<h1>{productName}</h1>
<!-- simple binding -->
<span>{product.price}</span>
<!-- nested via key -->
<div style="color: {textColor}">{msg}</div>
<!-- in attributes and style -->
<a href="/products/{slug}">{name}</a>
<!-- in attribute values -->
Use the if attribute:
<span if="inStock">In Stock</span>
<span if="!inStock">Out of Stock</span>
<div if="type===physical">Ships to your door</div>
<div if="type===virtual">Instant download</div>
For variant tags (enum): if="tagName===value" (no quotes around value).
Negation: if="!tagName" for boolean, if="tagName!==value" for enum.
Iterate over repeated sub-contracts:
<li forEach="products" trackBy="id">
<a href="/products/{slug}">
<div>{name}</div>
<div>{price}</div>
</a>
</li>
forEach โ the repeated tag nametrackBy โ stable unique key for each item (must match contract's trackBy)Nested loops:
<div forEach="options" trackBy="_id">
<h3>{name}</h3>
<div forEach="choices" trackBy="choiceId">
<button ref="choiceButton">{name}</button>
</div>
</div>
Map elements to contract interactive tags using ref:
<button ref="addToCart">Add to Cart</button> <input value="{quantity}" ref="quantityInput" />
Key-based headless refs โ prefix with the key:
<button ref="rating.submitButton">Submit</button> <button ref="mt.happy">+1 Happy</button>
Refs inside forEach:
<div forEach="options" trackBy="_id">
<div forEach="choices" trackBy="choiceId">
<button ref="choiceButton">{name}</button>
</div>
</div>
Page-level refs (not from a headless contract) โ declare interactive tags on page.jay-contract and bind in jay-html:
<button ref="saveDraft">Save</button> <textarea ref="notesInput" value="{notes}"></textarea>
Handle them in page.ts via refs.saveDraft.onclick(...) โ never document.querySelector for elements the page template renders.
Jay Stack owns the DOM. In page.ts and headfull components:
ref, if, forEach, {bindings}).refs.myRef.exec$((el) => โฆ) inside event handlers only.document.querySelector, document.body.appendChild, or build UI with document.createElement in loops.document mousemove/mouseup listeners.See skill jay-dom-refs and agent-kit/developer/component-refs.md.
Data merged into parent ViewState under a key. Use when you have one instance of a component per page.
<head>
<script
type="application/jay-headless"
plugin="wix-stores"
contract="product-page"
key="productPage"
></script>
</head>
<body>
<h1>{productPage.productName}</h1>
<span>{productPage.price}</span>
<button ref="productPage.addToCartButton">Add to Cart</button>
<!-- Nested repeated sub-contracts -->
<div forEach="productPage.options" trackBy="_id">
<h3>{name}</h3>
<div forEach="choices" trackBy="choiceId">
<button ref="choiceButton">{name}</button>
</div>
</div>
</body>
Each instance has its own props and inline template. Use when you have multiple instances or need to pass props.
First, declare the headless import without a key:
<head>
<script
type="application/jay-headless"
plugin="product-widget"
contract="product-widget"
></script>
</head>
Then use <jay:contract-name> tags with props:
<!-- Static props -->
<jay:product-widget productId="prod-1">
<h3>{name}</h3>
<div>${price}</div>
<button ref="addToCart">Add</button>
</jay:product-widget>
<!-- Multiple instances -->
<jay:product-widget productId="prod-2">
<h3>{name}</h3>
<button ref="addToCart">Add</button>
</jay:product-widget>
With forEach (dynamic props from parent data):
<div forEach="featuredProducts" trackBy="_id">
<jay:product-widget productId="{_id}">
<h3>{name}</h3>
<div>${price}</div>
<button ref="addToCart">Add</button>
</jay:product-widget>
</div>
Inside <jay:...>, bindings resolve to that instance's contract tags (not the parent).
Import a local component (with its own rendering logic):
<script type="application/jay-headfull" src="./todo" names="TodoComponent"></script>
<jay:TodoComponent props="{todoProps}"></jay:TodoComponent>
Inline <style>:
<head>
<style>
.product-card {
border: 1px solid #ccc;
padding: 16px;
}
.price {
font-weight: bold;
color: #2d7d2d;
}
</style>
</head>
External stylesheets:
<link rel="stylesheet" href="../../styles/theme.css" />
Dynamic style bindings:
<div style="color: {textColor}; width: {width}px">styled</div>
A page can define its own data contract in page.jay-contract:
<script type="application/jay-data" contract="./page.jay-contract"></script>
This declares the page's own ViewState. Tags are bound directly (no key prefix).
Pages live under src/pages/. Directory names become URL segments.
src/pages/
โโโ page.jay-html โ /
โโโ about/
โ โโโ page.jay-html โ /about
โโโ products/
โ โโโ page.jay-html โ /products
โ โโโ [slug]/
โ โโโ page.jay-html โ /products/:slug
โโโ blog/
โ โโโ page.jay-html โ /blog
โ โโโ [[slug]]/
โ โโโ page.jay-html โ /blog/:slug (optional param)
โโโ files/
โโโ [...path]/
โโโ page.jay-html โ /files/* (catch-all)
| Syntax | Meaning | Example |
|---|---|---|
[param] | Required parameter | [slug] โ /products/:slug |
[[param]] | Optional parameter | [[slug]] โ /blog or /blog/my-post |
[...param] | Catch-all | [...path] โ matches any sub-path |
Static routes match before dynamic routes:
[param] โ required dynamic param[[param]] โ optional param[...param] โ catch-all โ lowest priorityYou can create a static override alongside a dynamic route:
src/pages/products/
โโโ [slug]/page.jay-html # dynamic: /products/:slug
โโโ ceramic-flower-vase/page.jay-html # static override: /products/ceramic-flower-vase
Each page directory can contain:
| File | Purpose |
|---|---|
page.jay-html | Template (required for rendering) |
page.jay-contract | Page-level data contract |
page.conf.yaml | Configuration โ which headless components to use |
page.conf.yaml example:
used_components:
- plugin: '@jay-framework/wix-stores'
contract: product-page
key: productPage
For SSG with dynamic routes, the plugin component provides a loadParams generator. Discover available params:
yarn jay-stack params wix-stores/product-page
# Output: [{"slug": "blue-shirt"}, {"slug": "red-hat"}, ...]
The contract may declare params:
name: product-page
params:
slug: string
tags:
- tag: productName
type: data
dataType: string
A product page at src/pages/products/[slug]/page.jay-html:
<html>
<head>
<script type="application/jay-data" contract="./page.jay-contract"></script>
<script
type="application/jay-headless"
plugin="product-rating"
contract="product-rating"
key="rating"
></script>
<link rel="stylesheet" href="../../../styles/product.css" />
</head>
<body>
<h1>{name}</h1>
<h2>${price}</h2>
<p>{sku}</p>
<div if="type===physical">Shipping available</div>
<div if="type===virtual">Digital download</div>
<div if="!inStock">Out of stock</div>
<div if="inStock">
<button ref="add-to-cart">Add to Cart</button>
</div>
<!-- Headless rating widget (key-based) -->
<div>
<span>โ
{rating.rating} ({rating.totalReviews} reviews)</span>
<button ref="rating.star1">โ
</button>
<button ref="rating.star2">โ
</button>
<button ref="rating.star3">โ
</button>
<button ref="rating.star4">โ
</button>
<button ref="rating.star5">โ
</button>
<p>Your rating: {rating.userRating}</p>
<button ref="rating.submitButton">Submit</button>
</div>
</body>
</html>