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

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:

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:

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:

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.