# soup

> Query and manipulate raw markup via CSS selectors, without losing original formatting

Latest version **0.2.3** (published 2024-05-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install soup
pnpm add soup
yarn add soup
bun add soup
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.3 |
| Published | 2024-05-31 |
| First published | 2014-01-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 20.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 5 |
| Maintainers | callumlocke |

## Links

- npm: https://www.npmjs.com/package/soup
- Repository: https://github.com/callumlocke/soup
- Homepage: https://github.com/callumlocke/soup#readme
- Issues: https://github.com/callumlocke/soup/issues
- npm.io page: https://npm.io/package/soup

## Dependencies (2)

- [cheerio](https://npm.io/package/cheerio.md) ^1.0.0-rc.12
- [htmlparser2](https://npm.io/package/htmlparser2.md) ^9.1.0

## Recent versions

- 0.2.3 (latest) — 2024-05-31
- 0.2.2 — 2024-05-31
- 0.2.1 — 2024-05-31
- 0.1.5 — 2015-11-02
- 0.1.4 — 2015-11-02
- 0.1.3 — 2014-02-12
- 0.1.2 — 2014-02-12
- 0.1.1 — 2014-02-12
- 0.1.0 — 2014-02-12
- 0.0.9 — 2014-01-21
- 0.0.8 — 2014-01-20
- 0.0.7 — 2014-01-20
- 0.0.5 — 2014-01-20
- 0.0.4 — 2014-01-20
- 0.0.3 — 2014-01-16
- … 1 more at https://npm.io/package/soup/versions

## README

# soup

[![NPM version][npm-image]][npm-url]

> As of v0.2.2, now fixed to work with modern runtimes – tested on Node v21 and Bun.

A little library for querying and manipulating tag soup via CSS selectors.

It manipulates the string itself (rather than operating on a parsed DOM and then re-exporting it). So it retains all the syntactic/formatting nuances of the original, such as:

- attribute quotes or lack thereof,
- whitespace,
- invalid-but-parseable stuff,
- omitted closing tags, etc.

Use cases:

- build tasks/plugins that need to manipulate markup without parsing away all the original formatting;
- GUI webpage design tools that need to combine hand-coded HTML with WYSIWYG-driven edits;
- anywhere else you need to make automated, light-touch changes to other people's markup.

## Usage

```sh
$ npm install soup
```

```js
var Soup = require('soup')

soup = new Soup('<div class=thing><img src=cat.jpg></div>')

// Change the img src
soup.setAttribute('img', 'src', 'dog.jpg')
soup.toString() // <div class=thing><img src=dog.jpg></div>

// Add a class to the div
soup.setAttribute('.thing', 'class', function (oldValue) {
  return oldValue + ' another'
})
soup.toString() // <div class="thing another"><img src=dog.jpg></div>
```

### Selectors

Soup uses [Cheerio](https://github.com/MatthewMueller/cheerio) under the hood for finding elements to update, so you can use any CSS3 selector in the methods below.

### Methods

#### setAttribute(selector, attributeName, newValue)

- `newValue` can be:
  - any string – to set the attribute's value
  - `true` – to set it as a boolean attribute (eg `required`)
  - `false` – to delete the attribute
  - `null` – for "no change"
  - a function – which should decide what to do and return the correct value (as a string, boolean, or `null`). The function will be passed these arguments (NB. indices are relative to the start of the whole HTML string):
    1. the current value
    2. the start index of the attribute
    3. the end index of the attribute
    4. the start index of the element
    5. the end index of the element
- Soup will respect the original quote style of each attribute it updates whenever possible (but quotes will be added to non-quoted values if necessitated by characters in the new value).

Example – adding a query string to all image URLs:

```js
soup.setAttribute('img', 'src', function (oldValue) {
  return oldValue + '?12345'
})
```

#### getAttribute(selector, attributeName, callback)

Same as `.setAttribute()`, except that any return value from your callback will be ignored.

#### setInnerHTML(selector, attributeName, newHTML)

- `newHTML` can be:
  - a string of HTML
  - a function that returns a string of HTML
    - this will be passed the oldHTML
  - `null` for "no change"

Example – appending new content inside an element:

```js
soup.setInnerHTML('#foo', function (oldHTML) {
  return oldHTML + '<p>appended content</p>'
})
```

## License

Copyright (c) 2014 Callum Locke. Licensed under the MIT license.

[npm-url]: https://npmjs.org/package/soup
[npm-image]: https://img.shields.io/npm/v/soup.svg?style=flat-square
[travis-url]: http://travis-ci.org/callumlocke/soup
[travis-image]: https://img.shields.io/travis/callumlocke/soup.svg?style=flat-square&label=Linux%20build
[depstat-url]: https://david-dm.org/callumlocke/soup
[depstat-image]: https://img.shields.io/david/callumlocke/soup.svg?style=flat-square
[devDepstat-url]: https://david-dm.org/callumlocke/soup
[devDepstat-image]: https://img.shields.io/david/dev/callumlocke/soup.svg?style=flat-square#info=devDependencies

---
_Source: https://npm.io/package/soup · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._