Skip to content

Scraping HTML Tables with Cheerio

Cheerio makes table extraction a two-step job: select the table, then walk its rows and cells.

OUTPUT FORMATSHTMLJSONMarkdown

The approach below uses ordinary CSS selectors and the find/each traversal pattern to build an array of row objects from a small sample table.

The extraction pattern

Load the HTML string into a Cheerio object, select the table element with a CSS selector, then iterate over every tr. Inside each row, iterate over td and th cells. Collecting each cell's text into a row object gives you one record per table row. The supplied sample code (code0001) demonstrates exactly this: it loads a three-column table, selects table, loops rows with find('tr').each, loops cells with find('td, th').each, and pushes each row object into a tableData array.

What the sample table produces

The sample table has headers Name, Age, and Occupation, followed by two data rows (Yasoob, 35, Software Engineer; Pierre, 28, Product Manager). The supplied code keys each row object by the cell's text and stores the cell index as the value. That yields three objects: {Name: 0, Age: 1, Occupation: 2}, {'35': 1, Yasoob: 0, 'Software Engineer': 2}, and {'28': 1, Pierre: 0, 'Product Manager': 2}. Notice the second and third objects are keyed by cell values rather than by column names — a useful illustration of why the key strategy matters.

Choosing a row-key strategy

The sample's text-as-key approach is simple but fragile: data rows do not inherit the header names, so each row ends up keyed by its own values. For most real tables you want one of two patterns. Header-keyed: read the first row's th cells once, then map each data row's cells to those header names by position. Positional: store each row as an array of cell texts and keep the header row separately. Use header-keyed when column order is stable and you need named fields; use positional when headers are missing or duplicated.

Pre-flight checklist

Before trusting an extraction, confirm: (1) the table selector matches exactly one table, or you have a plan for multiple tables; (2) header cells are read before data rows; (3) each row's cell count matches the header count; (4) whitespace in cell text is trimmed; (5) nested tables or colspan/rowspan cells are handled or excluded; (6) the output is validated against a known row count.

Empty output vs malformed rows

An empty tableData array usually means the selector did not match — check the table tag, class, or id. A non-empty array with wrong keys or missing fields usually means the row/cell traversal is off: for example, th cells were not included in the cell loop, or a data row has fewer cells than the header. Distinguishing these two cases early saves debugging time.

Selector-to-output map

Selector table → the table element. Selector tr → one iteration per row. Selector td, th → one iteration per cell within a row. Cell text → the value written into the row object. Cell index j → the position stored in the sample's object. tableData → the final array of row objects.

Frequently asked questions

Do I need a headless browser to scrape a table with Cheerio?

No. Cheerio parses an HTML string you already have. If the table is rendered by JavaScript after page load, you need to obtain the rendered HTML first, then pass it to Cheerio.

Why does the sample code key rows by cell text instead of column names?

The sample is a minimal demonstration. It writes each cell's text as the object key and the cell index as the value, so data rows end up keyed by their own values. For production output, read header cells first and map data cells to those header names by position.

How do I handle a table with colspan or rowspan?

Cheerio's text extraction does not expand merged cells. Either exclude merged rows from the simple traversal or build a position-aware parser that tracks column spans before assigning values.