Style Types

CSS-like style properties and the stylesheet system.

DocxStyleRule

The core CSS-like style descriptor. All properties use familiar CSS names.

interface DocxStyleRule {
  // ── Text ──
  fontSize?: UnitValue
  fontWeight?: FontWeight
  fontStyle?: 'italic' | 'normal'
  bold?: boolean
  italic?: boolean
  fontFamily?: LiteralUnion<'Arial' | 'Calibri' | 'Times New Roman'>
  fontFamilyEastAsia?: string // independent Chinese, Japanese, and Korean font
  color?: string | HexColor
  backgroundColor?: string | HexColor
  highlight?: HighlightColor
  underline?: boolean | 'single' | 'double'
  strike?: boolean
  doubleStrike?: boolean
  allCaps?: boolean
  smallCaps?: boolean
  subScript?: boolean
  superScript?: boolean
  rightToLeft?: boolean
  emboss?: boolean
  imprint?: boolean
  characterSpacing?: number
  letterSpacing?: UnitValue

  // ── Spacing ──
  lineHeight?: number | UnitValue
  keepLines?: boolean
  keepNext?: boolean
  pageBreakBefore?: boolean
  widowControl?: boolean

  // ── Alignment ──
  textAlign?: TextAlign
  textIndent?: UnitValue
  verticalAlign?: VerticalAlign
  outlineLevel?: number
  tabStops?: TabStopRule[]

  // ── Box model ──
  margin?:
    | UnitValue
    | `${string} ${string}`
    | `${string} ${string} ${string} ${string}`
  marginTop?: UnitValue
  marginBottom?: UnitValue
  marginLeft?: UnitValue
  marginRight?: UnitValue

  // ── Border ──
  border?: BorderRule
  borderTop?: BorderRule
  borderBottom?: BorderRule
  borderLeft?: BorderRule
  borderRight?: BorderRule

  // ── Size ──
  width?: UnitValue
  height?: UnitValue

  // ── Escape hatch ──
  docx?: Record<string, unknown>
}

FontWeight

type FontWeight =
  'bold' | 'normal' | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900

HighlightColor

type HighlightColor =
  | 'black'
  | 'blue'
  | 'cyan'
  | 'darkBlue'
  | 'darkCyan'
  | 'darkGray'
  | 'darkGreen'
  | 'darkMagenta'
  | 'darkRed'
  | 'darkYellow'
  | 'green'
  | 'magenta'
  | 'none'
  | 'red'
  | 'white'
  | 'yellow'

TextAlign

type TextAlign = 'left' | 'center' | 'right' | 'justify'

TabStopRule

interface TabStopRule {
  position: UnitValue
  type:
    | 'bar'
    | 'center'
    | 'clear'
    | 'decimal'
    | 'end'
    | 'left'
    | 'num'
    | 'right'
    | 'start'
  leader?: 'dot' | 'hyphen' | 'middleDot' | 'none' | 'underscore'
}

VerticalAlign

type VerticalAlign = 'top' | 'middle' | 'bottom'

BorderRule

interface BorderRule {
  color?: string | HexColor
  style?: BorderStyle
  width?: UnitValue
}

BorderStyle

type BorderStyle = 'single' | 'double' | 'dashed' | 'dotted' | 'none'

StyleSheet & Inheritance

StyleSheet

type StyleSheet = Record<string, DocxStyleRule>

StyleSheetEntry

An entry in the stylesheet that may extend other styles.

interface StyleSheetEntry extends DocxStyleRule {
  /**
   * Single parent or ordered list of parents (later wins on conflict).
   */
  extends?: string | string[]
}

Style Inheritance via extends

Styles can extend other styles for CSS-like inheritance:

const styles = defineStyles({
  baseText: {
    fontSize: 11,
    fontFamily: 'Calibri',
    color: '#333',
  },
  body: {
    extends: 'baseText', // inherits fontSize, fontFamily, color
    lineHeight: 1.5, // override
  },
  h2: {
    extends: 'body', // 3-level chain: h2 → body → baseText
    fontSize: 18,
    fontWeight: 'bold',
  },
  warning: {
    extends: ['baseText', 'callout'], // multiple inheritance
    color: '#92400e',
  },
})

Style Cascade

Style resolution follows this priority (highest wins):

1. Inline style (passed directly to builder methods)
2. ClassName(s) from the stylesheet (merged left → right)
3. Defaults (per-element defaults from config)
4. Theme tokens ($category.key → resolved value)

Class names can be single strings, space-separated strings, or arrays:

doc.p('Hello', { className: 'accent' })
doc.p('Hello', { className: 'accent highlight' })
doc.p('Hello', { className: ['accent', 'highlight'] })

defineStyles()

Type-safe stylesheet factory with compile-time validation.

function defineStyles<T extends Record<string, StyleSheetEntry>>(
  styles: T & { [K in keyof T]: T[K] extends StyleSheetEntry ? T[K] : never },
): { [K in keyof T]: T[K] }

// Usage
const styles = defineStyles({
  accent: { color: '#2563eb', fontWeight: 'bold' },
  muted: { color: '#6b7280', fontSize: 10 },
})
// → styles.accent is { color: '#2563eb'; fontWeight: 'bold' }

Style Properties Reference

Category	Properties
Text	fontFamily, fontFamilyEastAsia, fontSize, fontWeight, fontStyle, bold, italic, color, highlight, underline, strike, doubleStrike, allCaps, smallCaps, subScript, superScript, rightToLeft, emboss, imprint, backgroundColor, characterSpacing, letterSpacing
Spacing	lineHeight, keepLines, keepNext, pageBreakBefore, widowControl
Margins	margin, marginTop, marginRight, marginBottom, marginLeft
Alignment	textAlign, textIndent, verticalAlign, outlineLevel, tabStops
Borders	border, borderTop, borderRight, borderBottom, borderLeft
Size	width, height
Escape	docx — merge directly into docxjs options

normalizeHexColor()

Normalize colors before passing them to native docx options. Core styles and built-in plugins use the same conversion. Three-digit hex colors expand to six digits and the leading # is removed. Other values retain native validation.

import { normalizeHexColor } from 'docx-kit'

normalizeHexColor('#f00') // 'ff0000'
normalizeHexColor('#123456') // '123456'

Paragraph styles also accept backgroundColor for whole-paragraph shading, including theme color tokens.