Etch Documentation

https://docs.etchwp.com
Admin
Etch is a WordPress plugin offering a visual website builder with drag-and-drop functionality,...
Tokens:200,491
Snippets:2,466
Trust Score:7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start the Connector with serve

Source: https://docs.etchwp.com/studio/etch-connector/cli-reference

Starts the connector process to which an Etch tab connects.

```bash
etch-connector serve [--ws-port 7331] [--control-port 7332] [--ws-host 127.0.0.1]  
```

--------------------------------

### Accessing Skills and References

Source: https://docs.etchwp.com/studio/public-api/skills

Example workflow for discovering available skills, loading guide content, and fetching specific reference documents.

```javascript
// 1. Discover what's available  
const skills = etch.skills.list();  
// → [{ name: "acss", description: "Automatic.css conventions…", metadata: {…}, references: ["colors.md", "spacing.md"] }, …]  
  
// 2. Load a full guide body by name  
const acss = etch.skills.get("acss");  
if (acss) {  
  console.log(acss.content); // the SKILL.md body as Markdown  
}  
  
// 3. Pull an individual reference only when you need it  
const colors = etch.skills.getReference("acss", "colors.md");  
if (colors) {  
  console.log(colors); // Markdown content of that reference  
}  
  
// Unknown names / references return undefined rather than throwing  
etch.skills.get("does-not-exist");                 // → undefined  
etch.skills.getReference("acss", "missing.md");    // → undefined  
```

--------------------------------

### Start Etch Connector

Source: https://docs.etchwp.com/studio/etch-connector/usage

Run this command in your AI agent's chat to initiate the connection to the Etch builder. No global installation is required.

```bash
npx @digital-gravy/etch-connector serve
```

--------------------------------

### AI Agent Quickstart Prompt

Source: https://docs.etchwp.com/studio/etch-connector/introduction

Copy and send this prompt to your AI agent to initiate the Etch Connector setup and guidance process.

```text
I'd like your help to work in Etch. Read the documentation page at https://docs.etchwp.com/etch-connector/usage and https://docs.etchwp.com/etch-connector/ai-agent-guide to learn how it works, run `npx @digital-gravy/etch-connector serve`, and guide me.  
```

--------------------------------

### Component Management Example

Source: https://docs.etchwp.com/public-api/components

Demonstrates how to list, get, create, update, and delete components using the EtchComponentsApi. Note that create, update, and delete persist immediately.

```typescript
// List and inspect
const all = etch.components.list();
const card = all.find((c) => c.key === "Card");
const full = etch.components.getJson(card!.id);
console.log(full.blocks);

// Create and configure
const id = await etch.components.createAsync("Callout");
await etch.components.updateAsync(id, {
  description: "A highlighted callout box",
  properties: [
    { name: "Heading", key: "heading", type: { primitive: "string" }, default: "Note" },
  ],
});

// Delete
await etch.components.deleteAsync(id);
```

--------------------------------

### Implement pagination facet example

Source: https://docs.etchwp.com/facets/third-party-facets/wp-grid-builder

A complete example showing the loop container and the associated pagination facet shortcode.

```html
<section data-etch-element="section">  
  <div class="posts-grid wpgb-content-1">  
    {#loop blogPosts as item}  
      <article>  
        {#if item.featuredImage}  
          <img src="{item.featuredImage.url}" alt="{item.featuredImage.alt}" />  
        {/if}  
        <h2><a href="{item.permalink.relative}">{item.title}</a></h2>  
        <p>{item.excerpt}</p>  
      </article>  
    {/loop}  
  </div>  
  
  [wpgb_facet id="your-facet-id" grid="wpgb-content-1"]  
</section>  
```

--------------------------------

### Custom media usage example

Source: https://docs.etchwp.com/studio/public-api/stylesheets

Example showing how to add a custom media query and list all current definitions.

```typescript
await etch.stylesheets.addCustomMediaAsync("--md", "(min-width: 768px)");  
etch.stylesheets.listCustomMedia(); // { "--md": "(min-width: 768px)", ... }  
```

--------------------------------

### includes() string examples

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/comparison-modifiers

Examples demonstrating the case-sensitive includes() method on a string value.

```text
{item.value.includes("foo")} → true
{item.value.includes("oo")} → true
{item.value.includes("Foo")} → false (case-sensitive)
{item.value.includes("test")} → false
{item.value.includes("bar", "Yes", "No")} → "Yes"
{item.value.includes("baz", "Yes", "No")} → "No"
```

--------------------------------

### includes() array examples

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/comparison-modifiers

Examples demonstrating the includes() method on an array, requiring exact element matches.

```text
{item.value.includes("foo")} → true
{item.value.includes("oo")} → false (no substring matching)
{item.value.includes("Foo")} → false (case-sensitive)
{item.value.includes("test")} → false
{item.value.includes("bar", "Yes", "No")} → "Yes"
{item.value.includes("baz", "Yes", "No")} → "No"
```

--------------------------------

### Managing CSS Variables

Source: https://docs.etchwp.com/studio/public-api/styles

Examples of setting, getting, listing, and removing CSS variables in both the default and named collections.

```javascript
// Default collection  
etch.styles.setVariable("--brand", "#0af");  
etch.styles.getVariable("--brand");   // "#0af"  
etch.styles.listVariables();          // { "--brand": "#0af", ... }  
etch.styles.removeVariable("--brand");  
  
// A named collection  
etch.styles.setVariable("--brand", "#0af", "theme-a");  
etch.styles.getVariable("--brand", "theme-a"); // "#0af"  
etch.styles.listVariables("theme-a");  
etch.styles.removeVariable("--brand", "theme-a");  
```

--------------------------------

### get(name)

Source: https://docs.etchwp.com/studio/public-api/skills

Retrieves the full details of a specific skill by its name, including the primary guide body.

```APIDOC
## get(name)

### Description
Retrieves the full guide body for a specific skill identified by its frontmatter name. Returns undefined if the skill is not found or the integration is not active.

### Signature
`get(name: string): SkillDetail | undefined`

### Parameters
- **name** (string) - Required - The unique identifier of the skill.

### Returns
- **SkillDetail | undefined** - The full skill detail object or undefined if not found.
```

--------------------------------

### startsWith() modifier examples

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/comparison-modifiers

Examples demonstrating the case-sensitive startsWith() method on a string value.

```text
{item.value.startsWith("Hello")} → true
{item.value.startsWith("H")} → true
{item.value.startsWith("hello")} → false (case-sensitive)
{item.value.startsWith("World")} → false
{item.value.startsWith("Hello", "Yes", "No")} → "Yes"
{item.value.startsWith("World", "Yes", "No")} → "No"
```

--------------------------------

### Component Management Workflow

Source: https://docs.etchwp.com/studio/public-api/components

Examples demonstrating how to list, inspect, create, configure, and delete components.

```typescript
// List and inspect  
const all = etch.components.list();  
const card = all.find((c) => c.key === "Card");  
const full = etch.components.getJson(card!.id);  
console.log(full.blocks);  
  
// Create and configure  
const id = await etch.components.createAsync("Callout");  
await etch.components.updateAsync(id, {  
  description: "A highlighted callout box",  
  properties: [  
    { name: "Heading", key: "heading", type: { primitive: "string" }, default: "Note" },  
  ],  
});  
  
// Delete  
await etch.components.deleteAsync(id);  
```

--------------------------------

### .less() comparison examples

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/comparison-modifiers

Examples of using .less() with numeric and string values, including custom return values.

```text
{item.value.less(30)} → true
{item.value.less(20)} → false
{item.value.less(25, "Is Less", "Is More")} → "Is More"
{item.value.less(30, "Is Less", "Is More")} → "Is Less"
{item.value.less("banana")} → true
{item.value.less("apple")} → false
{item.value.less("banana", "Is Less", "Is More")} → "Is Less"
{item.value.less("apple", "Is Less", "Is More")} → "Is More"
```

--------------------------------

### Comprehensive Loop Prop Example

Source: https://docs.etchwp.com/studio/components/props/prop-loop

A complete component example combining bracket notation, multiple modifiers, and loop arguments.

```html
<component>  
  <div>  
    {#loop props['featured-loop'].slice(0, props.maxItems.toInt())($offset: props.startFrom.toInt()) as item}  
      <article>  
        <h2>{item.title}</h2>  
        <p>{item.excerpt.truncateWords(20)}</p>  
      </article>  
    {/loop}  
  </div>  
</component>
```

--------------------------------

### .add() Modifier Examples

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/arithmetic-modifiers

Examples showing addition with numeric values and handling of non-numeric input.

```text
{item.value.add(3)}
```

```text
{item.value.add(3.25)}
```

```text
{item.value.add(3)}
```

--------------------------------

### .lessOrEqual() comparison examples

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/comparison-modifiers

Examples of using .lessOrEqual() with numeric and string values, including custom return values.

```text
{item.value.lessOrEqual(80)} → true
{item.value.lessOrEqual(79)} → false
{item.value.lessOrEqual(80, "Is Less or Equal", "Is Greater")} → "Is Less or Equal"
{item.value.lessOrEqual(79, "Is Less or Equal", "Is Greater")} → "Is Greater"
{item.value.lessOrEqual("banana")} → true
{item.value.lessOrEqual("apple")} → false
{item.value.lessOrEqual("banana", "Is Less or Equal", "Is Greater")} → "Is Less or Equal"
{item.value.lessOrEqual("apple", "Is Less or Equal", "Is Greater")} → "Is Greater"
```

--------------------------------

### Concrete Example: Etch Loop with Pagination Facet

Source: https://docs.etchwp.com/facets/third-party-facets/facetwp

This example demonstrates setting up an Etch loop with a FacetWP pagination facet. Ensure the `facetwp` argument is set to `true` in query args and the `facetwp-template` class is applied correctly.

```php
$query_args = [
  'post_type' => 'post',
  'posts_per_page' => 10,
  'order' => 'DESC',
  'facetwp' => 'true',
];
```

```html
<section data-etch-element="section">
  <div data-etch-element="container">
    <div class="posts-grid facetwp-template">
      {#loop blogPosts as item}
        <article>
          {#if item.featuredImage}
            <img src="{item.featuredImage.url}" alt="{item.featuredImage.alt}" />
          {/if}
          <h2><a href="{item.permalink.relative}">{item.title}</a></h2>
          <p>{item.excerpt}</p>
        </article>
      {/loop}
    </div>
    [facetwp facet="pagination"]
  </div>
</section>
```

--------------------------------

### Connect with options

Source: https://docs.etchwp.com/public-api

Example of calling getEtch with specific configuration options.

```typescript
const etch = getEtch({ apiVersion: "^1.0", id: "my-plugin" });
```

--------------------------------

### Usage Examples

Source: https://docs.etchwp.com/public-api/ai

Illustrative examples of how to use the EtchAiApi methods to manage AI presence during different stages of an agent's operation.

```APIDOC
## Usage Examples

### Announcing Presence and Performing Actions

```javascript
// Announce presence as work begins
etch.ai.setState("thinking");

etch.blocks.setText(id, "Draft");
etch.ai.setState("working");

// Hand back to the human
etch.ai.setState("waiting");

// Done — remove the overlay
etch.ai.hide(); // or etch.ai.setState("idle")
```

### Ensuring Presence is Cleared with `try...finally`

Presence should always be cleared to avoid leaving the overlay stuck on. Wrap agent operations in a `try...finally` block.

```javascript
etch.ai.setState("working");
try {
  // ... drive the builder ...
} finally {
  etch.ai.hide();
}
```
```

--------------------------------

### Start Etch Connector Server

Source: https://docs.etchwp.com/etch-connector/introduction

Run this command in your AI agent's chat to start the Etch Connector server. This allows the AI agent to connect to your Etch builder tab.

```bash
npx @digital-gravy/etch-connector serve
```

--------------------------------

### Example JSON Array

Source: https://docs.etchwp.com/studio/data-sources/json

A basic example of a JSON array containing objects for gym classes.

```json
[
	{ "name": "Yoga", "time": "09:00", "instructor": "Ada" },
	{ "name": "CrossFit", "time": "11:00", "instructor": "Grace" },
	{ "name": "Pilates", "time": "14:00", "instructor": "Ada" }
]
```

--------------------------------

### .subtract() Modifier Examples

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/arithmetic-modifiers

Examples showing subtraction with numeric values and handling of non-numeric input.

```text
{item.value.subtract(3)}
```

```text
{item.value.subtract(3.25)}
```

```text
{item.value.subtract(3)}
```

--------------------------------

### .divide() Modifier Examples

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/arithmetic-modifiers

Examples showing division with numeric values, handling of division by zero, and non-numeric input.

```text
{item.value.divide(3)}
```

```text
{item.value.divide(2.5)}
```

```text
{item.value.divide(0)}
```

```text
{item.value.divide(3)}
```

--------------------------------

### .multiply() Modifier Examples

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/arithmetic-modifiers

Examples showing multiplication with numeric values and handling of non-numeric input.

```text
{item.value.multiply(3)}
```

```text
{item.value.multiply(2.5)}
```

```text
{item.value.multiply(3)}
```

--------------------------------

### Advanced Inspection Examples with CDP

Source: https://docs.etchwp.com/studio/etch-connector/cli-reference

Examples of using the CDP mode to capture screenshots and retrieve computed CSS properties.

```bash
etch-connector shot --cdp -t etch -s .orbit -o orbit.png  
etch-connector computed --cdp -t etch -s .orbit__chip --props transform,animation-duration  
```

--------------------------------

### Install Etch Public API package

Source: https://docs.etchwp.com/public-api

Use npm to install the Etch public API package.

```bash
npm install @digital-gravy/etch-public-api
```

--------------------------------

### Comparison Syntax Examples

Source: https://docs.etchwp.com/conditional-logic/basic-conditions

Demonstrates the difference between string comparison and numerical evaluation.

```Etch
{#if props.rating === "2"}
```

```Etch
{#if props.rating >= 2}
```

```Etch
{#if props.rating >= "2"}
```

--------------------------------

### .mod() Modifier Examples

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/arithmetic-modifiers

Examples showing modulo operation with numeric values, handling of division by zero, and non-numeric input.

```text
{item.value.mod(3)}
```

```text
{item.value.mod(2)}
```

```text
{item.value.mod(0)}
```

```text
{item.value.mod(3)}
```

--------------------------------

### .greaterOrEqual() comparison examples

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/comparison-modifiers

Examples of using .greaterOrEqual() with numeric and string values, including custom return values.

```text
{item.value.greaterOrEqual(22)} → true
{item.value.greaterOrEqual(25)} → false
{item.value.greaterOrEqual(22, "Is Greater or Equal", "Is Less")} → "Is Greater or Equal"
{item.value.greaterOrEqual(25, "Is Greater or Equal", "Is Less")} → "Is Less"
{item.value.greaterOrEqual("banana")} → true
{item.value.greaterOrEqual("cherry")} → false
{item.value.greaterOrEqual("banana", "Is Greater or Equal", "Is Less")} → "Is Greater or Equal"
{item.value.greaterOrEqual("cherry", "Is Greater or Equal", "Is Less")} → "Is Less"
```

--------------------------------

### .greater() comparison examples

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/comparison-modifiers

Examples of using .greater() with numeric and string values, including custom return values.

```text
{item.value.greater(3)} → true
{item.value.greater(10)} → false
{item.value.greater(3, "Is Greater", "Is Not Greater")} → "Is Greater"
{item.value.greater(10, "Is Greater", "Is Not Greater")} → "Is Not Greater"
{item.value.greater("apple")} → true
{item.value.greater("banana")} → false
{item.value.greater("apple", "Is Greater", "Is Not Greater")} → "Is Greater"
{item.value.greater("banana", "Is Greater", "Is Not Greater")} → "Is Not Greater"
```

--------------------------------

### .keys() object example

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/basic-modifiers

Demonstrates retrieving keys from an object.

```json
"config": { "color": "red", "size": "lg", "weight": "bold" }
```

--------------------------------

### JSON Object Configuration

Source: https://docs.etchwp.com/studio/data-sources/json

An example of a JSON object structure suitable for site configuration.

```json
{
	"tagline": "Move better, feel better",
	"phone": "+43 1 234 5678",
	"email": "hello@example.com",
	"social": {
		"instagram": "https://instagram.com/example",
		"linkedin": "https://linkedin.com/company/example"
	}
}
```

--------------------------------

### Creating a block with a script

Source: https://docs.etchwp.com/public-api/blocks

Example of creating a block that includes a deferred module script to initialize instances.

```javascript
const id = etch.blocks.create({  
  type: "etch/element",  
  version: 1,  
  context: { name: "My Block" },  
  options: {},  
  children: [...],  
  tag: "div",  
  attributes: { class: "my-block" },  
  script: {  
    code: `document.querySelectorAll(".my-block").forEach(function (el) {  
  // initialise each instance  
});`,  
  },  
});  
```

--------------------------------

### Custom Media Management Example

Source: https://docs.etchwp.com/public-api/stylesheets

Shows how to add a custom media query definition and then list all defined custom media queries.

```javascript
await etch.stylesheets.addCustomMediaAsync("--md", "(min-width: 768px)");
etch.stylesheets.listCustomMedia(); // { "--md": "(min-width: 768px)", ... }
```

--------------------------------

### Basic Nav Component Setup

Source: https://docs.etchwp.com/components-native/basic-nav

Instructions on how to import and set up the Navigation and Burger components within your site's Header.

```APIDOC
## Basic Nav Component Setup

### Description
This section outlines the recommended approach to integrate the Basic Nav component into your website by importing prebuilt Navigation and Burger components.

### Steps
1. Ensure you have a Header component for your site.
2. Add a `{#slot}` (e.g., `{#slot right}`) within your Header component to place the Navigation and Burger components.
3. Copy the Navigation Component JSON using the provided button.
4. In Etch, paste the copied JSON into your Header slot using `cmd` + `v` (Mac) or `ctrl` + `v` (Windows).
5. Repeat steps 3 and 4 for the Burger Component.
6. Arrange the components within your Header slot (e.g., Navigation in the right slot, Burger next to it for mobile).
7. Verify desktop dropdowns/flyouts and mobile toggle behavior.
```

--------------------------------

### Options Page Syntax Examples

Source: https://docs.etchwp.com/integrations/custom-fields/options-pages

Use the `options` key with the provider namespace for ACF, Meta Box, or Jet Engine. No post context is required.

```html
{options.acf.field_name}
```

```html
{options.metabox.option_page_name.field_name}
```

```html
{options.jetengine.option_page_name.field_name}
```

--------------------------------

### Extract Array Portion with .slice()

Source: https://docs.etchwp.com/dynamic-data/dynamic-data-modifiers/basic-modifiers

Utilize `.slice()` to get a sub-array. Specify start and end indices; the end index is exclusive. Negative indices can be used for counting from the end.

```javascript
"value": ["ant", "bison", "camel", "duck", "elephant"]
```

```javascript
{item.value.slice(2)}
```

```javascript
{item.value.slice(2, 4)}
```

```javascript
{item.value.slice(-2)}
```

--------------------------------

### endsWith() modifier examples

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/comparison-modifiers

Examples demonstrating the case-sensitive endsWith() method on a string value.

```text
{item.value.endsWith("ld!")} → true
{item.value.endsWith("!")} → true
{item.value.endsWith("LD!")} → false (case-sensitive)
{item.value.endsWith("Hello")} → false
{item.value.endsWith("ld!", "Yes", "No")} → "Yes"
{item.value.endsWith("Hello", "Yes", "No")} → "No"
```

--------------------------------

### intersects() modifier examples

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/comparison-modifiers

Examples demonstrating the intersects() method to check for common elements between arrays.

```text
{item.value.intersects(["editor", "admin"])} → true
{item.value.intersects(["admin", "moderator"])} → false
{item.value.intersects(["author"])} → true
{item.value.intersects([])} → false
{item.value.intersects(["editor"], "Has Permission", "No Permission")} → "Has Permission"
{item.value.intersects(["admin"], "Has Permission", "No Permission")} → "No Permission"
```

--------------------------------

### Select Property Example

Source: https://docs.etchwp.com/studio/public-api/components

Example of defining a select property using a newline-separated string for options.

```typescript
const colorProp = {  
  name: "Color",  
  key: "color",  
  type: { primitive: "string", specialized: "select" },  
  selectOptionsString: ["Red : #ff0000", "Green : #00ff00", "Blue : #0000ff"].join("\n"),  
};  
```

--------------------------------

### Implement Recommended Content Structure

Source: https://docs.etchwp.com/elements/section

Example of a standard section implementation containing a heading, paragraph, and link within the container.

```html
<section data-etch-element="section">  
   <div data-etch-element="container">  
    <h2>About Our Services</h2>  
    <p>Discover the wide range of solutions we offer to help your business grow and succeed. Our team is dedicated to providing top-notch support and expertise for every project.</p>  
    <a href="/services/overview">Learn more about our services</a>  
  </div>  
</section>  
```

--------------------------------

### Navigate Builder UI and Open Content

Source: https://docs.etchwp.com/public-api/navigation

Demonstrates how to navigate between different builder areas using `goTo` and `openPostAsync`. It also shows how to retrieve the current UI location and check the active post ID.

```javascript
// Jump to the style manager and back
etch.navigation.goTo("style-manager");
console.log(etch.navigation.getCurrentPlace()); // "style-manager"
etch.navigation.goTo("builder");

// Open a different page on the canvas
const pages = await etch.navigation.listPostsAsync("page");
await etch.navigation.openPostAsync(pages[0].id);

// What's open right now?
console.log(etch.navigation.getActivePostId());
console.log(etch.navigation.isEditingTemplate());
```

--------------------------------

### Stylesheet Management Example

Source: https://docs.etchwp.com/public-api/stylesheets

Demonstrates the lifecycle of a stylesheet: creation, appending CSS, updating, reading, and deletion.

```javascript
// Create a stylesheet
const id = await etch.stylesheets.createAsync({
  name: "Utilities",
  css: ".u-hidden { display: none; }",
});

// Append to it (no save needed)
await etch.stylesheets.appendAsync(id, ".u-flex { display: flex; }");

// Rename / replace contents
await etch.stylesheets.updateAsync(id, { name: "Helpers" });

// Read back
const sheet = etch.stylesheets.get(id);
console.log(sheet.css);

// Delete
await etch.stylesheets.deleteAsync(id);
```

--------------------------------

### Starting point for JavaScript source

Source: https://docs.etchwp.com/studio/data-sources/javascript

The default starting point provided in the editor when creating a new JavaScript source.

```javascript
const category = args[0] ?? 'all';  
  
return [];  
```

--------------------------------

### EtchUiApi Usage Examples

Source: https://docs.etchwp.com/public-api/ui-and-history

Demonstrates how to use `EtchUiApi` methods to set color schemes, toggle interface visibility for a distraction-free mode, and exit the builder.

```javascript
// Force dark mode
etch.ui.setColorScheme("dark");

// Distraction-free: hide all chrome
if (!etch.ui.isInterfaceHidden()) etch.ui.toggleInterface();

// Leave the builder
etch.ui.exitToWordPress();

```

--------------------------------

### Navigation API Usage Examples

Source: https://docs.etchwp.com/studio/public-api/navigation

Common patterns for navigating the UI, opening posts, and checking the current state of the builder.

```javascript
// Jump to the style manager and back  
etch.navigation.goTo("style-manager");  
console.log(etch.navigation.getCurrentPlace()); // "style-manager"  
etch.navigation.goTo("builder");  
  
// Open a different page on the canvas  
const pages = await etch.navigation.listPostsAsync("page");  
await etch.navigation.openPostAsync(pages[0].id);  
  
// What's open right now?  
console.log(etch.navigation.getActivePostId());  
console.log(etch.navigation.isEditingTemplate());  
```

--------------------------------

### Serve Etch Connector

Source: https://docs.etchwp.com/etch-connector/usage

Run this command in your AI agent's chat to establish a connection with the Etch builder. No separate terminal or global installation is required.

```bash
npx @digital-gravy/etch-connector serve  

```

--------------------------------

### Arithmetic Modifier Examples

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/arithmetic-modifiers

Basic usage examples for arithmetic modifiers including add, subtract, multiply, divide, and mod.

```text
{price.add(5)}
```

```text
{price.subtract(3)}
```

```text
{quantity.multiply(2.5)}
```

```text
{total.divide(4)}
```

```text
{index.mod(3)}
```

--------------------------------

### Using .equal() for Equality Checks

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/comparison-modifiers

Demonstrates basic equality checks returning boolean values and custom results based on the comparison.

```text
{item.value.equal("active")} → true
{item.value.equal("inactive")} → false
{item.value.equal("active", "Is Equal", "Is Not Equal")} → "Is Equal"
{item.value.equal("inactive", "Is Equal", "Is Not Equal")} → "Is Not Equal"
```

--------------------------------

### Get remainder with integers using .mod()

Source: https://docs.etchwp.com/dynamic-data/dynamic-data-modifiers/arithmetic-modifiers

Demonstrates getting the remainder of an integer division using the .mod() modifier.

```dynamic data
{item.value.mod(3)}
```

--------------------------------

### Get remainder with floating-point numbers using .mod()

Source: https://docs.etchwp.com/dynamic-data/dynamic-data-modifiers/arithmetic-modifiers

Demonstrates getting the remainder of a floating-point division using the .mod() modifier.

```dynamic data
{item.value.mod(2)}
```

--------------------------------

### Serve Command

Source: https://docs.etchwp.com/etch-connector/cli-reference

Starts the etch-connector in serve mode, making it available for Etch tabs to connect. It allows configuration of WebSocket and control ports, as well as the host address.

```bash
etch-connector serve [--ws-port 7331] [--control-port 7332] [--ws-host 127.0.0.1]  

```

--------------------------------

### intersects() use case example

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/comparison-modifiers

A practical example of using intersects() within a loop to conditionally apply CSS classes based on user roles.

```html
{#loop users as user}  
  <div class="{user.roles.intersects(['admin', 'moderator'], 'user--privileged', 'user--standard')}">  
    {user.name}  
  </div>  
{/loop}
```

--------------------------------

### Example: Displaying Authors and Their Books with ACF

Source: https://docs.etchwp.com/integrations/custom-fields/relationship-fields

This example demonstrates looping through authors and their associated books using ACF relationship fields. It assumes an 'authors' WP Query and an 'author_books' relationship field.

```html
<section data-etch-element="section" class="authors-section">
    <div data-etch-element="container">
        <h2 class="authors-section__title">Authors & Their Books</h2>
        <ul class="authors-grid">
            {#loop authors as author}
                <li class="author-card">
                    <div class="author-card__info">
                        <h3 class="author-card__name">{author.title}</h3>
                        <div class="author-card__bio">{author.excerpt}</div>
                    </div>
                    <ul class="author-card__books-list">
                        {#loop author.acf.author_books as book}
                            <li class="author-card__book">
                                <a href="{book.permalink.relative}" class="author-card__book-link">
                                    {book.title}
                                </a>
                            </li>
                        {/loop}
                    </ul>
                </li>
            {/loop}
        </ul>
    </div>
</section>
```

--------------------------------

### Typical Loop Syntax

Source: https://docs.etchwp.com/studio/components/props/prop-loop

Standard loop syntax without using props.

```text
{#loop someLoop as item}{/loop}
```

--------------------------------

### Compare Typical and Prop-Based Loops

Source: https://docs.etchwp.com/components/props/prop-loop

Shows the syntax difference between a hardcoded loop and a dynamic loop prop.

```EtchWP
{#loop someLoop as item}{/loop}
```

```EtchWP
{#loop props.yourLoopProp as item}{/loop}
```

--------------------------------

### ACF Image Field Data Structure Example

Source: https://docs.etchwp.com/integrations/custom-fields/image-fields

An example of the JSON data structure returned by an ACF image field, showing available properties like ID, URL, sizes, and metadata.

```json
"acf": {  
  "my_image_field": {  
    "id": 123,  
    "url": "https://example.com/wp-content/uploads/2025/08/image.jpg",  
    "alt": "Image alt text",  
    "title": "Image title",  
    "caption": "Image caption",  
    "description": "Image description",  
    "filename": "image.jpg",  
    "sizes": {  
      "thumbnail": {  
        "url": "https://example.com/wp-content/uploads/2025/08/image-150x150.jpg",  
        "width": 150,  
        "height": 150  
      },  
      "medium": {  
        "url": "https://example.com/wp-content/uploads/2025/08/image-300x200.jpg",  
        "width": 300,  
        "height": 200  
      },  
      "large": {  
        "url": "https://example.com/wp-content/uploads/2025/08/image-1024x683.jpg",  
        "width": 1024,  
        "height": 683  
      },  
      "full": {  
        "url": "https://example.com/wp-content/uploads/2025/08/image.jpg",  
        "width": 1600,  
        "height": 1067  
      }  
    },  
    "srcset": "https://example.com/wp-content/uploads/2025/08/image-300x200.jpg 300w, https://example.com/wp-content/uploads/2025/08/image-1024x683.jpg 1024w, https://example.com/wp-content/uploads/2025/08/image.jpg 1600w",  
    "width": 1600,  
    "height": 1067,  
    "filesize": 256000,  
    "mime_type": "image/jpeg"  
  }  
}  
```

--------------------------------

### Initial Blog Post Grid HTML

Source: https://docs.etchwp.com/loops/basic-loops

The starting HTML structure for a blog post grid before applying the loop.

```html
<ul data-etch-element="container">  
  <li>  
    <article>  
      <figure><img src="https://placehold.co/600x400" alt="" /></figure>  
      <h2>Insert your heading here...</h2>  
      <p>Insert your text here...</p>  
      <a href="https://digitalgravy.co/">Click me</a>  
    </article>  
  </li>  
</ul>  
```

--------------------------------

### Meta Box Image Field Data Structure Example

Source: https://docs.etchwp.com/integrations/custom-fields/image-fields

An example of the JSON data structure returned by a Meta Box image field, showing available properties like ID, URL, sizes, and metadata.

```json
"metabox": {  
  "my_image_field": {  
    "id": 123,  
    "url": "https://example.com/wp-content/uploads/2025/08/image.jpg",  
    "alt": "Image alt text",  
    "title": "Image title",  
    "caption": "Image caption",  
    "description": "Image description",  
    "filename": "image.jpg",  
    "sizes": {  
      "thumbnail": {  
        "url": "https://example.com/wp-content/uploads/2025/08/image-150x150.jpg",  
        "width": 150,  
        "height": 150  
      },  
      "medium": {  
        "url": "https://example.com/wp-content/uploads/2025/08/image-300x200.jpg",  
        "width": 300,  
        "height": 200  
      },  
      "large": {  
        "url": "https://example.com/wp-content/uploads/2025/08/image-1024x683.jpg",  
        "width": 1024,  
        "height": 683  
      },  
      "full": {  
        "url": "https://example.com/wp-content/uploads/2025/08/image.jpg",  
        "width": 1600,  
        "height": 1067  
      }  
    },  
    "srcset": "https://example.com/wp-content/uploads/2025/08/image-300x200.jpg 300w, https://example.com/wp-content/uploads/2025/08/image-1024x683.jpg 1024w, https://example.com/wp-content/uploads/2025/08/image.jpg 1600w",  
    "width": 1600,  
    "height": 1067,  
    "filesize": 256000,  
    "mime_type": "image/jpeg"  
  }  
}  
```

--------------------------------

### Example Usage of Etch Skills API

Source: https://docs.etchwp.com/public-api/skills

Demonstrates the typical workflow for using the Etch Skills API: listing available skills, retrieving a full skill's content, and fetching a specific reference document. It also shows how the API handles unknown names or references by returning undefined.

```javascript
// 1. Discover what's available
const skills = etch.skills.list();
// → [{ name: "acss", description: "Automatic.css conventions…", metadata: {…}, references: ["colors.md", "spacing.md"] }, …]

// 2. Load a full guide body by name
const acss = etch.skills.get("acss");
if (acss) {
  console.log(acss.content); // the SKILL.md body as Markdown
}

// 3. Pull an individual reference only when you need it
const colors = etch.skills.getReference("acss", "colors.md");
if (colors) {
  console.log(colors); // Markdown content of that reference
}

// Unknown names / references return undefined rather than throwing
etch.skills.get("does-not-exist");                 // → undefined
etch.skills.getReference("acss", "missing.md");    // → undefined
```

--------------------------------

### ltrim modifier

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/basic-modifiers

Removes whitespace from the start of a string.

```text
{item.value.ltrim()}
```

--------------------------------

### Complete Component with Loop and Count Props

Source: https://docs.etchwp.com/studio/components/props/prop-loop

A full component example utilizing both a loop prop and a count prop.

```html
<component>  
  <div>  
    {#loop props.myLoop($count: props.myCount) as item}  
      <article>  
        <h2>{item.title}</h2>  
        <p>{item.excerpt}</p>  
      </article>  
    {/loop}  
  </div>  
</component>
```

--------------------------------

### .values() loop example

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/basic-modifiers

Loops over the values of an object.

```html
{#loop item.config.values() as value}  
  <span>{value}</span>  
{/loop}
```

--------------------------------

### Create a complete search archive layout

Source: https://docs.etchwp.com/templates/search-results-template

A full template example incorporating the search query parameter and a structured loop for displaying result cards.

```Etch
<main>  
  <section data-etch-element="section" class="search">  
    <div data-etch-element="container" class="search__header">  
      <h1 class="search__title">Search results for: {url.parameter.s}</h1>  
    </div>  
    <div data-etch-element="container" class="search__results">  
      {#loop mainQuery as item}  
        <article class="search-card">  
          <h2 class="search-card__title"><a href={item.permalink.relative}>{item.title}</a></h2>  
          <div class="search-card__description">{item.excerpt}</div>  
        </article>  
      {/loop}  
    </div>  
  </section>  
</main>  

```

--------------------------------

### startsWith modifier

Source: https://docs.etchwp.com/studio/dynamic-data/dynamic-data-modifiers/comparison-modifiers

Checks if a string starts with a given string.

```text
{item.value.startsWith('Hel')}
```

--------------------------------

### Define Select Prop Options

Source: https://docs.etchwp.com/components/creating-component-variations

List of available options for a theme selection prop.

```text
dark  
light  
primary  
```
Tokens:
Raw