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.

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:

import { createTailwindParser } from "@cordel/react-docx";

const parser = createTailwindParser(options);

You can also use the class directly:

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

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

Then use in your document:

<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

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

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

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:

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],
});

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

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:

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:

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.

Getting started

Components

API Reference

createTailwindParser

Options

Custom colors

Custom fonts

Custom handlers

Adding extra handlers

Replacing built-in handlers

Handler names

TailwindParseResult

Passing to render

​createTailwindParser

​Options

​Custom colors

​Custom fonts

​Custom handlers

​Adding extra handlers

​Replacing built-in handlers

​Handler names

​TailwindParseResult

​Passing to render

createTailwindParser

Options

Custom colors

Custom fonts

Custom handlers

Adding extra handlers

Replacing built-in handlers

Handler names

TailwindParseResult

Passing to render