# 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.

Source: https://hypaxel.libs.vensas.de/docs/examples  
Last updated: 2026-11-20

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

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

```ts
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

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

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

### Java

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

```csharp
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

```rust
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

```python
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

```ts
import { CONTENT_TYPE, webStream } from 'hypaxel'

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

### Go with error handling

```go
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

```java
@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

```php
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](https://hypaxel.libs.vensas.de/docs/nodejs#browsers) for how the module is loaded.

### A download link with `toBlob`

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

```ts
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.

```ts
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`.

```ts
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](https://hypaxel.libs.vensas.de/docs/troubleshooting#untrusted-uploads-and-the-shared-string-table)).

### Python

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

```python
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

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

```csharp
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

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

```rust
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

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

```go
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

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

```java
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

```csharp
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

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

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

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

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

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

```csharp
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

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

```ts
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

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

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

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

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

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

```csharp
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

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

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

```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]);
```
