XlsxWriter

A high-performance Elixir library for creating Excel (.xlsx) spreadsheets. Built with the powerful rust_xlsxwriter crate via Rustler NIF, providing excellent speed and memory efficiency.

Features

• ⚡ Fast: Leverages Rust for high-performance spreadsheet generation
• 🧠 Memory efficient: Handles large datasets without excessive memory usage
• 📊 Rich formatting: Support for fonts, colors, borders, alignment, number formats, and more
• 🎨 Cell borders: Apply borders with 13 styles and customizable colors per side
• 🖼️ Images: Embed images directly into spreadsheets
• 📐 Layout control: Set column widths, row heights, bulk sizing for ranges, freeze panes, hide rows/columns
• 🧮 Formulas: Write Excel formulas and functions with optional formatting
• 🔗 Hyperlinks: Create clickable URLs with custom display text
• ✅ Booleans: Native Excel TRUE/FALSE values
• 🔀 Merged cells: Combine multiple cells into one
• 🔍 Autofilter: Add dropdown filters to headers
• ❄️ Freeze panes: Lock headers when scrolling
• 📄 Multiple sheets: Create workbooks with multiple worksheets
• 💬 Comments: Add notes to cells for documentation and context
• 🔧 Simple API: Clean, pipe-friendly Elixir interface

Quick Start

Low-Level API

For precise control over cell positioning and advanced features:

# Create a simple spreadsheet
sheet =
  XlsxWriter.new_sheet("Sales Data")
  |> XlsxWriter.write(0, 0, "Product", format: [:bold])
  |> XlsxWriter.write(0, 1, "Sales", format: [:bold])
  |> XlsxWriter.write(0, 2, "In Stock", format: [:bold])
  |> XlsxWriter.write(1, 0, "Widget A")
  |> XlsxWriter.write(1, 1, 1500.50, format: [{:num_format, "$#,##0.00"}])
  |> XlsxWriter.write_boolean(1, 2, true)

{:ok, content} = XlsxWriter.generate([sheet])

File.write!("sales.xlsx", content)

Simple API (Builder) - ⚠️ Experimental

For quickly generating files without manually tracking cell positions:

alias XlsxWriter.Builder

Builder.create()
|> Builder.add_sheet("Sales Data")
|> Builder.add_rows([
  [{"Product", format: [:bold]}, {"Sales", format: [:bold]}, {"In Stock", format: [:bold]}],
  ["Widget A", {1500.50, format: [{:num_format, "$#,##0.00"}]}, true]
])
|> Builder.write_file("sales.xlsx")

Note: The Builder API is experimental and may change in future releases. See the Builder API section for details.

Comprehensive Demo

Want to see all features in action? Run the comprehensive demo script that showcases every XlsxWriter capability:

mix run examples/comprehensive_demo.exs

This generates comprehensive_demo.xlsx with 9 sheets demonstrating:

• All data types (strings, numbers, dates, booleans, formulas, URLs)
• Font formatting (colors, sizes, styles, families, super/subscript)
• Cell borders (all 13 styles, colored, per-side)
• Background colors and fill patterns
• Text alignment and number formats
• Layout features (freeze panes, autofilter, hidden rows/columns, range operations)
• Merged cells
• Cell comments/notes
• A complete invoice example

Perfect for learning the library or as a reference!

Builder API (High-Level) - ⚠️ Experimental

The XlsxWriter.Builder module provides a simplified API for generating Excel files without manually tracking cell positions. Perfect for quickly dumping data into spreadsheets.

Quick example:

alias XlsxWriter.Builder

Builder.create()
|> Builder.add_sheet("Summary")
|> Builder.add_rows([
  [{"Name", format: [:bold]}, {"Age", format: [:bold]}],
  ["Alice", 30],
  ["Bob", 25]
])
|> Builder.write_file("report.xlsx")

Try it out:

mix run examples/builder_demo.exs

This creates 5 example files showing formatting, multi-sheet workbooks, large datasets (1000+ rows), and more.

Full documentation: See the Builder API Guide for complete documentation, API reference, and examples.

Note: The Builder API is experimental and may change in future releases.

Guides

For detailed documentation and examples:

• Getting Started - Basic usage, data types, and your first spreadsheet
• Builder API - High-level API for quick data export (⚠️ Experimental)
• Advanced Formatting - Fonts, colors, borders, and number formats
• Layout Features - Freeze panes, merged cells, autofilters, and more

Examples

Basic Example

sheet =
  XlsxWriter.new_sheet("Report")
  |> XlsxWriter.write(0, 0, "Name", format: [:bold])
  |> XlsxWriter.write(0, 1, "Value", format: [:bold])
  |> XlsxWriter.write(1, 0, "Item A")
  |> XlsxWriter.write(1, 1, 100)

{:ok, content} = XlsxWriter.generate([sheet])
File.write!("report.xlsx", content)

Multi-Sheet Example

summary = XlsxWriter.new_sheet("Summary")
  |> XlsxWriter.write(0, 0, "Total", format: [:bold])
  |> XlsxWriter.write(0, 1, 1000)

details = XlsxWriter.new_sheet("Details")
  |> XlsxWriter.write(0, 0, "Item", format: [:bold])
  |> XlsxWriter.write(1, 0, "Widget")

{:ok, content} = XlsxWriter.generate([summary, details])
File.write!("workbook.xlsx", content)

For more examples covering data types, formatting, layouts, and advanced features, see the guides.

Formatting Options

XlsxWriter supports extensive cell formatting through the format: parameter:

# Font styles
format: [:bold]
format: [:italic, :strikethrough]
format: [{:font_color, "#FF0000"}, {:font_size, 14}]

# Alignment and background
format: [{:align, :center}]
format: [{:bg_color, "#FFFF00"}]

# Borders
format: [{:border, :thin}]
format: [{:border_top, :thick}, {:border_bottom, :double}]

# Number formats
format: [{:num_format, "$#,##0.00"}]  # Currency
format: [{:num_format, "0.00%"}]      # Percentage

# Combine multiple options
format: [:bold, {:align, :center}, {:bg_color, "#4472C4"}]

Supported formatting:

• Fonts: bold, italic, strikethrough, font color, font size, font family, underline, superscript, subscript
• Alignment: left, center, right
• Colors: background colors, font colors, border colors
• Borders: 13 styles (thin, medium, thick, dashed, dotted, double, etc.) for all sides
• Numbers: currency, percentage, thousands separator, decimals, dates, times, custom formats

For complete formatting documentation with examples, see the Advanced Formatting Guide.

Installation

The package is available on Hex. Add xlsx_writer to your list of dependencies in mix.exs:

def deps do
  [
    {:xlsx_writer, "~> 0.7.0"}
  ]
end

Then run:

mix deps.get

Documentation

Full documentation is available at HexDocs.

Development

Publishing a new version

Follow the rustler_precompiled guide:

1. Update version number in mix.exs and this README
2. Create and push a new tag: git tag v0.1.x && git push origin main --tags
3. Wait for GitHub Actions to build all NIFs
4. Download precompiled assets: mix rustler_precompiled.download XlsxWriter.RustXlsxWriter --all
5. Publish to Hex: mix hex.publish

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Running Tests

mix test

Building Documentation

mix docs

Copyright and License

Copyright (c) 2025 Floatpays

This work is free. You can redistribute it and/or modify it under the terms of the MIT License. See the LICENSE.md file for more details.