Skip to content
Docs: ExamplesMenu

Examples

Hypaxel examples by use case: export to a file, stream an HTTP download, download from the browser, read a workbook or upload, map records, styled reports and tables.

v0.3.0 unreleasedLast updated View as Markdown

These examples are organized by task, each shown in several languages. They are taken from the language guides, where you will find the surrounding explanation and further variants.

Export to a file#

Write a list of records to orders.xlsx. Mapped records get a styled, frozen header row and an auto filter.

Python#

hypaxel.to_xlsx(df, "orders.xlsx")                       # pandas or polars DataFrame
data: bytes = hypaxel.to_xlsx(orders)                    # list of dicts / dataclasses / models
hypaxel.to_xlsx(df, "out.xlsx", column_formats={"amount": "#,##0.00"})

Node.js#

import { toBuffer, writeFile } from 'hypaxel'

await writeFile('orders.xlsx', orders)

const buffer = await toBuffer(orders, {
  sheetName: 'Orders',
  columns: ['id', { key: 'customer', header: 'Customer', width: 30 }, { key: 'amount', numFormat: '#,##0.00' }],
})

Go#

func export(path string, orders []Order) error {
	file, err := os.Create(path)
	if err != nil {
		return err
	}
	defer file.Close()

	w := hypaxel.NewWriter(file)
	if err := hypaxel.WriteSheet(w, "Orders", orders); err != nil {
		return err
	}
	return w.Close()
}

PHP#

$rows = $pdo->query('SELECT id, customer, amount FROM orders', PDO::FETCH_ASSOC);
Xlsx::writeFile('orders.xlsx', $rows);

Java#

try (XlsxWriter writer = XlsxWriter.create(Path.of("orders.xlsx"))) {
    writer.writeWorksheet("Orders", Order.class, orders);
}

Stream an HTTP download#

The workbook is written into the response body while rows are read from the source. Memory per request stays bounded.

ASP.NET Core#

using Hypaxel.AspNetCore;

app.MapGet("/orders.xlsx", (AppDb db) =>
    Results.Extensions.Excel(db.Orders.AsNoTracking().AsAsyncEnumerable(), "orders"));

app.MapGet("/report.xlsx", () => Results.Extensions.Excel(async (writer, ct) =>
{
    var sheet = writer.AddWorksheet("Summary");
    await sheet.AddRowAsync(["Generated", DateTime.UtcNow], ct);
    await writer.WriteWorksheetAsync("Orders", LoadOrders(), ct);
}, fileName: "report"));

axum#

async fn export(State(pool): State<PgPool>) -> Xlsx {
    let rows = sqlx::query_as::<_, Order>("SELECT ...").fetch(&pool);
    Xlsx::from_stream("Orders", rows).filename("export.xlsx")
}

Django#

from django.http import StreamingHttpResponse

def export(request):
    response = StreamingHttpResponse(
        hypaxel.stream_records(Order.objects.values("id", "customer", "amount").iterator()),
        content_type=hypaxel.CONTENT_TYPE,
    )
    response["Content-Disposition"] = 'attachment; filename="orders.xlsx"'
    return response

Next.js route handler#

import { CONTENT_TYPE, webStream } from 'hypaxel'

export function GET() {
  return new Response(webStream(fetchOrders()), { headers: { 'Content-Type': CONTENT_TYPE } })
}

Go with error handling#

func export(rw http.ResponseWriter, r *http.Request) {
	err := hypaxelhttp.Serve(rw, r, "report.xlsx", func(w *hypaxel.Writer) error {
		sheet, err := w.AddSheet("Report")
		if err != nil {
			return err
		}
		return sheet.WriteRow("Generated", time.Now())
	})
	if err != nil && !errors.Is(err, hypaxelhttp.ErrPartial) {
		http.Error(rw, "export failed", http.StatusInternalServerError)
	}
}

Spring MVC#

@GetMapping("/orders.xlsx")
public ResponseEntity<StreamingResponseBody> orders() {
    StreamingResponseBody body = out -> {
        try (XlsxWriter writer = XlsxWriter.create(out);
                Stream<Order> orders = repository.streamAll()) {
            writer.writeWorksheet("Orders", Order.class, orders);
        }
    };
    return ResponseEntity.ok()
            .contentType(MediaType.parseMediaType(XlsxWriter.CONTENT_TYPE))
            .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"orders.xlsx\"")
            .body(body);
}

Laravel#

Route::get('/orders.xlsx', fn () => response()->streamDownload(
    static fn () => Xlsx::output(DB::table('orders')->select('id', 'customer', 'amount')->orderBy('id')->cursor()),
    'orders.xlsx',
    ['Content-Type' => Xlsx::CONTENT_TYPE],
));

Download from the browser#

The Node.js package runs in browsers on a WebAssembly build, with the same API. See Browsers for how the module is loaded.

toBlob builds the whole file in memory, compressed, and returns a Blob with the XLSX content type.

import { toBlob } from 'hypaxel'

const blob = await toBlob(rows, { columns: ['id', { key: 'amount', numFormat: '#,##0.00' }] })
const link = Object.assign(document.createElement('a'), { href: URL.createObjectURL(blob), download: 'orders.xlsx' })
link.click()
URL.revokeObjectURL(link.href)

Large exports with webStream#

webStream is pull-based: rows are produced as the consumer reads. Written to disk through the File System Access API, memory stays bounded.

import { webStream } from 'hypaxel'

const handle = await window.showSaveFilePicker({ suggestedName: 'orders.xlsx' })
await webStream(fetchOrders()).pipeTo(await handle.createWritable())

The Writer in a browser#

new Writer() is synchronous, so load the module first. In browsers, finish() returns a Uint8Array.

import { init, Writer } from 'hypaxel'

await init()
const workbook = new Writer()
const sheet = workbook.addWorksheet('Orders')
sheet.writeRow(['Product', 'Units'])
sheet.writeRow(['Widget', 3])
const bytes = workbook.finish()

Read a workbook#

Rows are read one at a time. Memory is bounded by the workbook’s shared string table plus one row. Rows and columns are 1-based. Reading is available in .NET, Rust, Python, Go and Java; Node.js and PHP do not read yet. For files from untrusted sources, lower the shared string cap as in the upload examples (why).

Python#

import hypaxel

records = hypaxel.read_records("orders.xlsx", "Orders")     # [{"Product": "Widget", ...}, ...]
df = hypaxel.read_dataframe("orders.xlsx")                   # pandas; library="polars" for polars

for row in hypaxel.iter_rows("orders.xlsx", "Orders"):      # one list per row, streamed
    print(row)                                               # ['Widget', 3, 9.99, datetime(...)]

An upload, read from bytes:

from fastapi import HTTPException, UploadFile

@app.post("/orders/import")
async def import_orders(file: UploadFile):
    data = await file.read()
    try:
        records = hypaxel.read_records(data, "Orders", max_shared_strings_bytes=64 * 1024 * 1024)
    except hypaxel.XlsxError as e:                           # .xls, encrypted, damaged, missing sheet
        raise HTTPException(400, str(e))
    return {"rows": len(records)}

.NET#

using Hypaxel;

using var reader = XlsxReader.Open("orders.xlsx");
using var rows = reader.OpenWorksheet("Orders");        // or OpenWorksheet(0)
while (rows.Read())
{
    var row = rows.Row;                                 // reused for every row
    if (row.TryGetString(1, out var customer)
        && row.TryGetDouble(3, out var amount)
        && row.TryGetDateTime(4, out var placed))
    {
        Console.WriteLine($"{row.Number}: {customer} {amount} {placed:yyyy-MM-dd}");
    }
}

A request body cannot seek, so copy it first:

using var buffer = new MemoryStream();
await request.Body.CopyToAsync(buffer);
buffer.Position = 0;

using var reader = new XlsxReader(buffer, new XlsxReaderOptions { MaxSharedStringsBytes = 64L * 1024 * 1024 });

Rust#

use hypaxel::XlsxReader;

let mut reader = XlsxReader::open("orders.xlsx")?;
let mut rows = reader.worksheet("Orders")?;             // or worksheet_at(0)
while let Some(row) = rows.next_row()? {
    if let (Some(customer), Some(amount)) = (row.get(1).as_str(), row.get(3).as_f64()) {
        println!("{}: {customer} {amount}", row.number());
    }
}

From bytes in memory, with a lower cap:

use hypaxel::{ReadOptions, XlsxReader};

let options = ReadOptions::new().max_shared_strings_bytes(64 * 1024 * 1024);
let mut reader = XlsxReader::with_options(std::io::Cursor::new(upload), &options)?;

Go#

r, err := hypaxel.OpenReader("orders.xlsx")
if err != nil {
	return err
}
defer r.Close()

rows, err := r.Rows("Orders")                   // or r.RowsAt(0)
if err != nil {
	return err
}
for row, err := range rows.All() {
	if err != nil {
		return err
	}
	amount, _ := row.Get(3).Float()
	fmt.Println(row.Index(), row.Get(1).Text(), amount)
}
return nil

From bytes in memory, with a lower cap:

r, err := hypaxel.NewReader(bytes.NewReader(data), int64(len(data)), hypaxel.WithMaxSharedStringsBytes(64<<20))
if err != nil {
	return err // errors.Is(err, hypaxel.ErrInvalidFile) for .xls, encrypted or non-spreadsheet files
}
defer r.Close()

Java#

try (XlsxReader reader = XlsxReader.open(Path.of("orders.xlsx"));
        SheetReader rows = reader.worksheet("Orders")) {             // or worksheet(0)
    for (Row row = rows.nextRow(); row != null; row = rows.nextRow()) {
        String customer = row.getString(1);
        double amount = row.getNumber(3);                           // NaN if not a number
        LocalDateTime placed = row.getLocalDateTime(4);             // null if not a date
    }
}

nextRow() reuses one Row. To collect rows, use stream(), which yields copies:

ReadOptions options = ReadOptions.builder().maxSharedStringsBytes(64L * 1024 * 1024).build();
try (XlsxReader reader = XlsxReader.open(uploadBytes, options);
        Stream<Row> rows = reader.worksheet(0).stream()) {
    List<List<Object>> table = rows.map(Row::toList).toList();
}

Export records and objects#

Map your own types to columns with headers, widths and number formats.

.NET#

public sealed class Order
{
    [ExcelColumn("Order #", Order = 0, Width = 10)]
    public int Id { get; init; }

    public string Customer { get; init; } = "";

    [ExcelColumn(NumberFormat = "yyyy-mm-dd")]
    public DateOnly Date { get; init; }

    [ExcelColumn(NumberFormat = "#,##0.00")]
    public decimal Amount { get; init; }

    [ExcelIgnore]
    public string InternalNote { get; init; } = "";
}

await writer.WriteWorksheetAsync("Orders", orders);

Rust#

#[derive(serde::Serialize)]
struct Order {
    #[serde(rename = "Order #")]
    id: u32,
    customer: String,
    #[serde(serialize_with = "hypaxel::records::excel_date")]   // native, sortable Excel date
    placed: chrono::NaiveDate,
    amount: f64,
    note: Option<String>,                                       // None → empty cell
}

writer.write_sheet_records("Orders", &orders)?;

Python#

@dataclass
class Order:
    id: int
    customer: str
    amount: float
    placed: dt.date

wb = hypaxel.Writer("orders.xlsx")
hypaxel.write_records(wb, "Orders", orders, column_formats={"amount": "#,##0.00", "placed": "yyyy-mm-dd"})
hypaxel.write_dataframe(wb, "Summary", summary_df, index=True)
wb.finish()

Go#

type Order struct {
	ID       int       `xlsx:"Order #,width=10"`
	Customer string    `xlsx:"Customer,width=30"`
	Created  time.Time `xlsx:"Created,date"`
	Amount   float64   `xlsx:"Amount,width=14,format=#,##0.00"`
	Internal string    `xlsx:"-"`
}

Java#

public record Order(
        @ExcelColumn(name = "Order #", order = 0, width = 10) int id,
        String customer,
        @ExcelColumn(format = "#,##0.00") BigDecimal amount,
        @ExcelColumn(format = "yyyy-mm-dd") LocalDate created,
        @ExcelIgnore String internalNote) {
}

PHP#

$bytes = Xlsx::toString($orders, sheetName: 'Orders', columns: [
    'id',
    new ColumnSpec('customer', header: 'Customer', width: 30),
    new ColumnSpec('amount', numberFormat: '#,##0.00'),
]);

Styled report with a formula total#

A header style, a money format, a frozen header row, fixed column widths and a SUM formula. Formulas are stored without cached results; Excel calculates them when the file opens.

.NET#

await using var writer = XlsxWriter.Create("report.xlsx");

var header = writer.AddStyle(new CellStyle
{
    Font = new Font { Bold = true, Color = ExcelColor.White },
    Fill = new Fill(ExcelColor.FromHex("#305496")),
});
var money = writer.AddStyle(new CellStyle { NumberFormat = NumberFormats.Thousands2 });

var sheet = writer.AddWorksheet("Sales", new WorksheetOptions { FrozenRows = 1 }.SetColumnWidths(20, 12, 14));

await sheet.AddRowAsync(CellValue.From("Product", header), CellValue.From("Date", header), CellValue.From("Revenue", header));
await sheet.AddRowAsync("Widget", new DateOnly(2024, 5, 1), CellValue.From(1234.5, money));
await sheet.AddRowAsync("Gadget", new DateOnly(2024, 5, 2), CellValue.From(99.99, money));
await sheet.AddRowAsync("Total", CellValue.Empty, CellValue.Formula("SUM(C2:C3)", money));

await writer.CompleteAsync();

Python#

with hypaxel.Writer("report.xlsx") as wb:
    header = wb.add_style(bold=True, font_color="#FFFFFF", fill="#305496", align="center")
    money = wb.add_style(num_format="#,##0.00")

    ws = wb.add_worksheet("Sales", freeze_rows=1, column_widths=[20, 12, 14])
    ws.write_row(["Product", "Date", "Revenue"], style=header)
    ws.write_rows([
        ("Widget", dt.date(2024, 5, 1), Styled(1234.5, money)),
        ("Gadget", dt.date(2024, 5, 2), Styled(99.99, money)),
    ])
    ws.write_row(["Total", None, Styled(Formula("SUM(C2:C3)"), money)])

Node.js#

const workbook = new Writer()
const header = workbook.addStyle({ bold: true, fontColor: '#FFFFFF', fill: '#305496', align: 'center' })
const money = workbook.addStyle({ numFormat: '#,##0.00' })

const sheet = workbook.addWorksheet('Sales', { freezeRows: 1, columnWidths: [20, 12, 14] })
sheet.writeRow(['Product', 'Date', 'Revenue'], header)
sheet.writeRows([
  ['Widget', new Date(2024, 4, 1), new Styled(1234.5, money)],
  ['Gadget', new Date(2024, 4, 2), new Styled(99.99, money)],
])
sheet.writeRow(['Total', null, new Styled(new Formula('SUM(C2:C3)'), money)])

writeFileSync('report.xlsx', workbook.finish())

Java#

try (XlsxWriter writer = XlsxWriter.create(Path.of("report.xlsx"))) {
    StyleId header = writer.addStyle(Style.builder()
            .bold().fontColor(Color.WHITE).fill(Color.hex("#305496")).align(HorizontalAlignment.CENTER).build());
    StyleId money = writer.addStyle(Style.builder().numberFormat(NumberFormats.THOUSANDS2).build());

    Worksheet sheet = writer.addWorksheet("Sales",
            SheetOptions.builder().freezeRows(1).columnWidths(20, 12, 14).build());
    sheet.addStyledRow(header, "Product", "Date", "Revenue");
    sheet.write("Widget").write(LocalDate.of(2024, 5, 1)).write(1234.5, money).endRow();
    sheet.write("Gadget").write(LocalDate.of(2024, 5, 2)).write(99.99, money).endRow();
    sheet.write("Total").skipCells(1).writeFormula("SUM(C2:C3)", money).endRow();
}

PHP#

$writer = Writer::toFile('report.xlsx');
$header = $writer->addStyle(Style::create()->bold()->fontColor('#FFFFFF')->fill('#305496')->align(HorizontalAlignment::Center));
$money = $writer->addStyle(Style::create()->numberFormat('#,##0.00'));

$sheet = $writer->addWorksheet('Sales', new SheetOptions(freezeRows: 1, columnWidths: [20, 12, 14]));
$sheet->writeRow(['Product', 'Date', 'Revenue'], $header);
$sheet->writeRows([
    ['Widget', new DateTimeImmutable('2024-05-01'), new Styled(1234.5, $money)],
    ['Gadget', new DateTimeImmutable('2024-05-02'), new Styled(99.99, $money)],
]);
$sheet->writeRow(['Total', null, new Styled(new Formula('SUM(C2:C3)'), $money)]);

$writer->finish();

Tables, row grouping and auto-fit#

Declare auto-fit and the deepest outline level when you add the worksheet, then write grouped rows and turn the range into an Excel table. Table columns must match the header texts exactly.

Rust#

use hypaxel::{AutoFit, RowOptions, SheetOptions, Table, TableStyle};

let options = SheetOptions::new()
    .autofit_columns()            // or .autofit(AutoFit::new().sample_rows(5_000).max_width(60.0))
    .row_outline_levels(1)        // deepest grouping level used on this sheet (1–7)
    .outline_summary_above();     // group buttons on the row above each group
let mut sheet = writer.add_worksheet_with("Regions", &options)?;

sheet.add_row(("Region", "Revenue"))?;
sheet.add_row(("North", 300))?;
sheet.begin_row_with(&RowOptions::new().outline_level(1))?.add_row(("Store A", 120))?;
sheet.begin_row_with(&RowOptions::new().outline_level(1).hidden())?.add_row(("Store B", 180))?;

let last = sheet.row();
sheet.add_table(&Table::new(1, 1, last, 2).name("Regions").columns(["Region", "Revenue"]).style(TableStyle::Medium(9)))?;

Python#

ws = wb.add_worksheet("Regions", autofit=True, row_outline_levels=1, outline_summary_above=True)
ws.write_row(["Region", "Revenue"])
ws.write_row(["North", 300])
ws.write_row(["Store A", 120], outline_level=1)
ws.write_row(["Store B", 180], outline_level=1, hidden=True)
ws.add_table(1, 1, ws.row, 2, columns=["Region", "Revenue"], name="Regions", style="TableStyleMedium9")

Node.js#

const sheet = writer.addWorksheet('Regions', { autofit: true, rowOutlineLevels: 1, outlineSummaryAbove: true })
sheet.writeRow(['Region', 'Revenue'])
sheet.writeRow(['North', 300])
sheet.beginRow({ outlineLevel: 1 })
sheet.writeRow(['Store A', 120])
sheet.addTable(1, 1, sheet.row, 2, { name: 'Regions', columns: ['Region', 'Revenue'], style: 'TableStyleMedium9' })

.NET#

var sheet = writer.AddWorksheet("Orders");
await sheet.AddRowAsync("Product", "Units");
await sheet.AddRowAsync("Widget", 3);
await sheet.AddRowAsync("Gadget", 5);

sheet.AddTable(new ExcelTable(1, 1, sheet.RowNumber, 2)
{
    Name = "Orders",                    // optional: Table1, Table2, … otherwise
    Columns = ["Product", "Units"],     // must match the header row
    Style = TableStyle.Medium(9),       // Light(1–21), Medium(1–28), Dark(1–11) or None
});

Go#

sheet, _ := w.AddSheetOptions("Regions", hypaxel.SheetOptions{RowOutlineLevels: 2, OutlineSummaryAbove: true})
sheet.WriteRow("North", 300)
sheet.BeginRow(hypaxel.RowOptions{OutlineLevel: 1})
sheet.WriteRow("Store A", 120)
sheet.BeginRow(hypaxel.RowOptions{OutlineLevel: 2, Hidden: true})
sheet.WriteRow("Till 1", 60)

Java#

Worksheet sheet = writer.addWorksheet("Regions", SheetOptions.builder()
        .rowOutlineLevels(1)        // deepest level used, 0-7
        .outlineSummaryAbove()      // the group's button sits on the row above it
        .build());

sheet.addRow("North", 300);
sheet.beginRow(RowOptions.builder().outlineLevel(1).build()).addRow("Store A", 120);   // addRow fills the begun row
sheet.beginRow(RowOptions.builder().outlineLevel(1).hidden().build())                  // a collapsed group's rows are hidden
        .write("Store B").write(180).endRow();

PHP#

$sheet = $writer->addWorksheet('Regions', new SheetOptions(rowOutlineLevels: 2, outlineSummaryAbove: true));
$sheet->writeRow(['North', 300]);
$sheet->beginRow(outlineLevel: 1)->writeRow(['Store A', 120]);
$sheet->beginRow(outlineLevel: 2, hidden: true)->writeRow(['Till 1', 60]);
$sheet->beginRow(outlineLevel: 1, collapsed: true)->writeRow(['Store B', 180]);