How to Style Lists in html-to-pdfmake: CSS, Defaults, and Overrides

You can style lists in html-to-pdfmake using built-in default margins, inline CSS properties like list-style-type, or the options.defaultStyles parameter to override any PDFMake-compatible property.

The html-to-pdfmake library converts HTML <ul> and <ol> elements into PDFMake list objects with configurable styling. According to the aymkdn/html-to-pdfmake source code, you can control bullet types, margins, and item formatting through three distinct mechanisms that merge together during conversion.

Built-in Default Styles

The library ships with opinionated defaults defined in index.js at lines 75-78. The defaultStyles object applies a base margin to every unordered list:

// index.js – default style for <ul>
this.defaultStyles = {
  // …
  ul: {marginBottom:5, marginLeft:5},
  // …
}

These defaults are automatically applied to all lists unless you explicitly override or delete them via the options.defaultStyles parameter.

Inline CSS and HTML Attributes

When parsing <ul> or <ol> elements, the converter inspects both the type attribute and CSS properties list-style / list-style-type. In index.js at lines 85-94, the parser maps these values to PDFMake's type field:

case "OL":
case "UL": {
  ret[nodeNameLowerCase] = (ret.stack || ret.text).slice(0);
  // …
  // map HTML `type` attribute or CSS `list-style-type`/`list-style`
  if (ret.listStyle || ret.listStyleType) ret.type = ret.listStyle || ret.listStyleType;
}

Valid CSS values like disc, circle, square, lower-alpha, or upper-roman transfer directly to the PDFMake type property, controlling the bullet or numbering format.

Overriding with options.defaultStyles

For fine-grained control over margins, colors, or fonts, pass a defaultStyles object in the options. The changeDefaultStyles helper (implemented in index.js at lines 87-100) merges your custom values with the built-in table:

const html = '<ul><li>Item 1</li><li>Item 2</li></ul>';
const pdfDef = htmlToPdfMake(html, {
  defaultStyles: {
    ul: {marginLeft: 30, color: 'red'},   // change left margin & bullet colour
    li: {fontSize: 12, bold: true}        // style individual list items
  }
});

You can remove a default entirely by setting its value to null, or delete specific properties by setting them to empty strings.

Advanced Styling with data-pdfmake

For properties not covered by standard CSS, use the data-pdfmake attribute to inject raw PDFMake configuration directly into the HTML:

<ul data-pdfmake='{"type":"square"}'>
  <li>One</li>
  <li>Two</li>
</ul>

This attribute is parsed by the parseElement logic and applied after CSS processing, allowing you to set any PDFMake-supported list option.

Practical Code Examples

Basic List with Defaults

const html = `
  <ul>
    <li>Apple</li>
    <li>Banana</li>
  </ul>`;
const def = htmlToPdfMake(html);
console.log(def);

Output excerpt:

{
  "ul": [
    {"text":"Apple"},
    {"text":"Banana"}
  ],
  "margin": [0,5,0,10]          // comes from the default `ul` style
}

Custom Bullet Type via CSS

<ul style="list-style-type: lower-alpha;">
  <li>First</li>
  <li>Second</li>
</ul>

const def = htmlToPdfMake(html);

The generated object includes "type":"lower-alpha", rendering bullets as "a.", "b.", etc.

Full Customization via Options

const html = `
  <ol start="5" style="list-style-type: upper-roman;">
    <li>Alpha</li>
    <li>Beta</li>
  </ol>`;
const def = htmlToPdfMake(html, {
  defaultStyles: {
    ol: {marginLeft: 40, color: '#0066CC'},   // indented, blue numbers
    li: {fontSize: 14, italics: true}       // larger, italic items
  }
});

Result excerpt:

{
  "ol": [
    {"text":"Alpha"},
    {"text":"Beta"}
  ],
  "type":"upper-roman",
  "start":5,
  "margin": [40,0,0,0],
  "color":"#0066CC",
  "fontSize":14,
  "italics":true
}

Summary

• Built-in defaults in index.js apply automatic margins to all lists via the defaultStyles object.
• Inline CSS properties like list-style-type map directly to PDFMake's type field for bullet customization.
• Options override via defaultStyles allows complete control over margins, colors, and fonts, merged by the changeDefaultStyles helper.
• data-pdfmake attributes bypass CSS limitations to inject raw PDFMake properties directly.

Frequently Asked Questions

Can I change the bullet style in html-to-pdfmake?

Yes. Use standard CSS list-style-type (e.g., style="list-style-type: square;") or the HTML type attribute. The parser in index.js maps these values to PDFMake's type property, supporting values like disc, circle, square, lower-alpha, and upper-roman.

How do I remove default margins from lists?

Pass null or an empty object to the defaultStyles option for the specific tag. For example: htmlToPdfMake(html, {defaultStyles: {ul: null}}) removes all default styling for unordered lists, or set specific properties to empty strings to delete them individually.

Does html-to-pdfmake support nested list styling?

Yes. The converter processes nested <ul> and <ol> structures recursively. Each level receives its own styling context, allowing you to target specific depths via CSS classes or the defaultStyles option using standard CSS selectors in your HTML.

What CSS properties work for list styling in html-to-pdfmake?

Any CSS property that PDFMake understands can be applied. Common list-related properties include margin-left, margin-bottom, color, font-size, and list-style-type. Complex CSS like padding or border may not translate unless supported by PDFMake's styling schema.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}