<!-- BusyBot node reference — https://busybot.net/tools/html-extract/ -->

> Node: HTML Extract (`html_extract`) · Action (binary) · v1
> Category: Core Nodes · Credentials: none
> Updated: 2026-08-16

# HTML Extract

> Extract data from HTML using CSS selectors

## Overview

The HTML Extract tool parses HTML content and extracts data based on user-defined CSS selector rules. It supports two source modes: (1) JSON mode reads HTML from a specified JSON property on the input item, (2) Binary mode reads HTML from a binary data property. Each extraction rule specifies a CSS selector, a return type (text, html, attribute, or value), and whether to return a single value or an array of all matches. Output is JSON with extracted key-value pairs. Upstream binary data is forwarded unchanged.

**Category:** Core Nodes  
**Tool Name:** `html_extract`  
**Version:** 1

**Appearance:** Icon: `lucide-Code` | Color: `#333377`

## Node Type

**Action (Binary)** — handles file/binary data operations

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool does not require any credentials.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Source Data | `options` | No | `json` | Whether HTML should be read from binary data or a JSON property. |
| | | | | Options: `binary` (read HTML from a binary data property), `json` (read HTML from a JSON property on the item) |
| Input Binary Field | `string` | Yes | `data` | The name of the input binary field containing the HTML file to be extracted. _(shown when Source Data is `binary`)_ |
| JSON Property | `string` | Yes | `data` | Name of the JSON property containing the HTML to extract data from. The property can contain a string or an array of strings. Supports dot-notation (e.g., "response.body"). _(shown when Source Data is `json`)_ |
| Extraction Values | `fixedCollection` | No | `{}` | Define one or more extraction rules. Each rule uses a CSS selector to find elements and extracts the specified data. |
| — Key | `string` | No | — | The key under which the extracted value should be saved in the output JSON. |
| — CSS Selector | `string` | No | — | The CSS selector to match HTML elements (e.g., "h1", ".price", "#main a", "table tr td:nth-child(2)"). |
| — Return Value | `options` | No | `text` | What kind of data should be returned from matched elements. |
| | | | | Options: `attribute` (get an attribute value like "class" from an element), `html` (get the inner HTML the element contains), `text` (get only the text content of the element), `value` (get value of an input, select, or textarea element) |
| — Attribute | `string` | No | — | The name of the attribute to return the value of (e.g., "href", "src", "data-id"). _(shown when Return Value is `attribute`)_ |
| — Return Array | `boolean` | No | `false` | Whether to return values as an array. If true and multiple elements match, each produces a separate array entry. If false, all matched text is concatenated into a single string. |
| Options | `collection` | No | `{}` | Whitespace handling for extracted values. |
| — Trim Values | `boolean` | No | `true` | Whether to automatically remove spaces and newlines from the beginning and end of extracted values. |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

The extracted values are **added to** the input item's JSON — each rule writes its result under its own **Key**, and everything the item already carried, including binary data, comes through unchanged.

```json
{
  "url": "https://example.com/product/42",
  "productName": "Standing desk",
  "prices": ["£349.00", "£299.00"],
  "links": ["https://example.com/a", "https://example.com/b"]
}
```

- A rule with **Return Array** on returns one entry per matched element; with it off, the matches are collapsed into a single value.
- A selector that matches nothing produces an empty array with **Return Array** on, and an empty value with it off — a page whose markup changed will not fail the item, it will quietly return nothing, so validate the values downstream if they are load-bearing.
- A **Key** that already exists on the item is overwritten.

**One item can produce several.** When **JSON Property** points at an array of HTML strings, the node emits one output item per string, each carrying the same input fields plus that string's extracted values. A single string produces a single item.

Reference the results downstream by expression, e.g. `{{ $json.productName }}`.

The item fails when the named JSON property does not exist, or when it holds something other than a string or an array of strings.

## Usage Examples

- Extract all product prices from an HTML page
- Get the title and meta description from HTML
- Extract all links (href attributes) from a webpage
- Parse an HTML table into structured data
- Extract text content from specific CSS-selected elements

## Example Configuration

Pull a heading and every link out of an HTML string on the item:

```json
{
  "type": "html_extract",
  "parameters": {
    "sourceData": "json",
    "dataPropertyName": "htmlContent",
    "extractionValues": {
      "values": [
        {
          "key": "title",
          "cssSelector": "h1",
          "returnValue": "text",
          "returnArray": false
        },
        {
          "key": "links",
          "cssSelector": "a",
          "returnValue": "attribute",
          "attribute": "href",
          "returnArray": true
        }
      ]
    }
  }
}
```

Extract from an uploaded HTML file, keeping the original whitespace:

```json
{
  "type": "html_extract",
  "parameters": {
    "sourceData": "binary",
    "dataPropertyName": "uploadedFile",
    "maxConcurrency": 5,
    "options": {
      "trimValues": false
    },
    "extractionValues": {
      "values": [
        {
          "key": "productName",
          "cssSelector": ".product-title",
          "returnValue": "text",
          "returnArray": false
        },
        {
          "key": "prices",
          "cssSelector": ".price",
          "returnValue": "text",
          "returnArray": true
        }
      ]
    }
  }
}
```

Read a meta tag out of a nested response property:

```json
{
  "type": "html_extract",
  "parameters": {
    "sourceData": "json",
    "dataPropertyName": "response.body.content",
    "options": {
      "trimValues": true
    },
    "extractionValues": {
      "values": [
        {
          "key": "description",
          "cssSelector": "meta[name='description']",
          "returnValue": "attribute",
          "attribute": "content",
          "returnArray": false
        }
      ]
    }
  }
}
```

Scrape several data points from a fetched page:

```json
{
  "type": "html_extract",
  "parameters": {
    "sourceData": "json",
    "dataPropertyName": "pageHtml",
    "maxConcurrency": 10,
    "options": {
      "trimValues": true
    },
    "extractionValues": {
      "values": [
        {
          "key": "pageTitle",
          "cssSelector": "title",
          "returnValue": "text",
          "returnArray": false
        },
        {
          "key": "allHeadings",
          "cssSelector": "h1, h2, h3",
          "returnValue": "text",
          "returnArray": true
        },
        {
          "key": "imageUrls",
          "cssSelector": "img",
          "returnValue": "attribute",
          "attribute": "src",
          "returnArray": true
        }
      ]
    }
  }
}
```

Analyse an HTML email attachment:

```json
{
  "type": "html_extract",
  "parameters": {
    "sourceData": "binary",
    "dataPropertyName": "emailAttachment",
    "maxConcurrency": 3,
    "options": {
      "trimValues": true
    },
    "extractionValues": {
      "values": [
        {
          "key": "senderName",
          "cssSelector": ".sender-info .name",
          "returnValue": "text",
          "returnArray": false
        },
        {
          "key": "actionLinks",
          "cssSelector": ".cta-button",
          "returnValue": "attribute",
          "attribute": "href",
          "returnArray": true
        }
      ]
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Parse HTML from JSON property or binary data and extract values using CSS selectors — outputs structured JSON key-value pairs.

### Key Points

1. **Data source flexibility** — the same field position serves two purposes: **Input Binary Field** for an uploaded or downloaded file, **JSON Property** for HTML already sitting on the item.
2. **CSS selector power** — any valid CSS selector works, including comma-separated groups like `h1, h2, h3` and structural selectors like `table tr td:nth-child(2)`.
3. **Array vs single values** — **Return Array** decides whether you get every match separately or one combined value.
4. **Attribute extraction** — set **Return Value** to `attribute` and name the attribute to read `href`, `src`, `content` or any `data-*` attribute.
5. **Performance tuning** — adjust **Max Concurrency** to match how many pages arrive at once.

### Notes

- This node extracts only. To render HTML, or to turn items into an HTML table, use the HTML node.
- Pair it with HTTP Request for scraping: fetch the page, then point **JSON Property** at the response body.