> ## Documentation Index
> Fetch the complete documentation index at: https://react-docx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tailwind Parser

Programmatic API for customizing how Tailwind classes map to DOCX properties. Use this when a `tailwind.config` file isn't enough — custom handlers, brand colors at runtime, or replacing built-in behavior.

```tsx theme={"dark"}
import { createTailwindParser, render } from "@cordel/react-docx";

const parser = createTailwindParser({
  colors: {
    brand: { 500: "0F4C81", 100: "E8F0FE" },
  },
});

await render(<MyDocument />, "./output.docx", { tailwindParser: parser });
```

***

## createTailwindParser

Factory function that returns a `TailwindParser` instance:

```tsx theme={"dark"}
import { createTailwindParser } from "@cordel/react-docx";

const parser = createTailwindParser(options);
```

You can also use the class directly:

```tsx theme={"dark"}
import { TailwindParser } from "@cordel/react-docx";

const parser = new TailwindParser(options);
```

***

## Options

| Option             | Type                                         | Description                                                      |
| ------------------ | -------------------------------------------- | ---------------------------------------------------------------- |
| `colors`           | `Record<string, Record<number, string>>`     | Custom color palette. Merged with built-in colors.               |
| `fontSizes`        | `Record<string, number>`                     | Custom font sizes (in half-points). Merged with built-ins.       |
| `fontFamilies`     | `Record<string, string>`                     | Custom font families. Merged with built-ins.                     |
| `extraHandlers`    | `ClassHandler[]`                             | Custom handlers prepended to the pipeline. Run before built-ins. |
| `replacedHandlers` | `Partial<Record<HandlerName, ClassHandler>>` | Replace specific built-in handlers by name.                      |

***

## Custom colors

```tsx theme={"dark"}
const parser = createTailwindParser({
  colors: {
    brand: {
      50: "EFF6FF",
      100: "DBEAFE",
      500: "3B82F6",
      700: "1D4ED8",
      900: "1E3A8A",
    },
    accent: {
      500: "F59E0B",
    },
  },
});
```

Then use in your document:

```tsx theme={"dark"}
<Text className="text-brand-500">Brand blue</Text>
<Paragraph className="bg-accent-500">Accent background</Paragraph>
```

Color values are hex strings without the `#` prefix.

***

## Custom fonts

```tsx theme={"dark"}
const parser = createTailwindParser({
  fontFamilies: {
    "font-heading": "Georgia",
    "font-code": "Fira Code",
  },
});
```

```tsx theme={"dark"}
<Text className="font-heading">Georgia heading</Text>
<Text className="font-code">Monospace code</Text>
```

***

## Custom handlers

A `ClassHandler` is a function that processes a Tailwind class and writes the result:

```typescript theme={"dark"}
type ClassHandler = (
  cls: string,
  result: TailwindParseResult,
  config: ParseConfig,
) => boolean;
```

Return `true` if the class was handled, `false` to pass it to the next handler.

### Adding extra handlers

Extra handlers run before the built-in pipeline:

```tsx theme={"dark"}
import { createTailwindParser } from "@cordel/react-docx";

const highlightHandler = (cls, result) => {
  if (cls === "highlight") {
    result.textStyles.backgroundColor = "FFFF00";
    result.textStyles.bold = true;
    return true;
  }
  return false;
};

const parser = createTailwindParser({
  extraHandlers: [highlightHandler],
});
```

```tsx theme={"dark"}
<Text className="highlight">Yellow bold text</Text>
```

### Replacing built-in handlers

Override a specific handler by name. You can delegate to the original via `defaultHandlerMap`:

```tsx theme={"dark"}
import { createTailwindParser, defaultHandlerMap } from "@cordel/react-docx";

const parser = createTailwindParser({
  replacedHandlers: {
    borders: (cls, result, config) => {
      // Custom logic for a specific class
      if (cls === "border-brand") {
        result.tableCellStyles.borders = {
          all: { width: 4, style: "single", color: "0F4C81" },
        };
        return true;
      }
      // Fall back to default for everything else
      return defaultHandlerMap.borders(cls, result, config);
    },
  },
});
```

***

## Handler names

All built-in handlers that can be replaced:

| Name                 | Handles                                                  |
| -------------------- | -------------------------------------------------------- |
| `textFormatting`     | Bold, italic, underline, strike, caps                    |
| `textColor`          | `text-{color}-{shade}` classes                           |
| `backgroundColor`    | `bg-{color}-{shade}` classes                             |
| `textAlignment`      | `text-left`, `text-center`, `text-right`, `text-justify` |
| `spacing`            | `mt-*`, `mb-*`, `ml-*`, `mr-*`, `indent-*`               |
| `lineHeight`         | `leading-*` classes                                      |
| `letterSpacing`      | `tracking-*` classes                                     |
| `borders`            | `border-*` classes (width, style, color, sides)          |
| `tableCellPadding`   | `p-*`, `px-*`, `py-*`, `pt-*`, `pb-*`                    |
| `tableCellAlignment` | `align-top`, `align-middle`, `align-bottom`              |
| `sizing`             | `w-*`, `h-*` for images                                  |
| `objectFit`          | `object-cover`, `object-contain`, `object-fill`          |
| `customAspectRatio`  | `aspect-*` classes                                       |
| `arbitraryColor`     | `text-[#hex]`, `bg-[#hex]`                               |
| `arbitraryFontSize`  | `text-[14px]`, `text-[12pt]`                             |

***

## TailwindParseResult

The result object that handlers write to:

```typescript theme={"dark"}
interface TailwindParseResult {
  textStyles: TextStyles;
  paragraphStyles: ParagraphStyles;
  genericStyles: GenericStyles;
  tableCellStyles: TableCellStyles;
}
```

Each field maps to a group of DOCX properties. Handlers set individual properties on these objects.

***

## Passing to render

Pass your parser to `render` or `renderToBuffer`:

```tsx theme={"dark"}
const parser = createTailwindParser({ /* ... */ });

await render(<MyDocument />, "./output.docx", {
  tailwindParser: parser,
});

// or
const { buffer } = await renderToBuffer(<MyDocument />, {
  tailwindParser: parser,
});
```

When no parser is provided, a default instance is used that loads from your `tailwind.config` file automatically.