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

> Learn how to style lists in html-to-pdfmake with CSS and override defaults. Customize list styles for your PDFs easily and effectively.

- Repository: [Aymeric/html-to-pdfmake](https://github.com/aymkdn/html-to-pdfmake)
- Tags: how-to-guide
- Published: 2026-02-26

---

**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`](https://github.com/aymkdn/html-to-pdfmake/blob/main/index.js) at lines 75-78. The `defaultStyles` object applies a base margin to every unordered list:

```js
// 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`](https://github.com/aymkdn/html-to-pdfmake/blob/main/index.js) at lines 85-94, the parser maps these values to PDFMake's `type` field:

```js
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`](https://github.com/aymkdn/html-to-pdfmake/blob/main/index.js) at lines 87-100) merges your custom values with the built-in table:

```js
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:

```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

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

```

Output excerpt:

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

```

### Custom Bullet Type via CSS

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

```

```js
const def = htmlToPdfMake(html);

```

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

### Full Customization via Options

```js
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:

```json
{
  "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`](https://github.com/aymkdn/html-to-pdfmake/blob/main/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`](https://github.com/aymkdn/html-to-pdfmake/blob/main/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.