API Reference

import "github.com/jpoz/werkbook"

If you need to inspect formula graph edges, also import github.com/jpoz/werkbook/formula because some dependency helpers return formula package types.

Constructors and Options

New

func New(opts ...Option) *File

Creates a new workbook. By default it contains one sheet named "Sheet1".

Options:

• FirstSheet(name string) - override the default first sheet name
• WithDate1904(enabled bool) - create the workbook in the 1904 date system

wb := werkbook.New()
wb := werkbook.New(werkbook.FirstSheet("Data"))
wb := werkbook.New(werkbook.FirstSheet("Data"), werkbook.WithDate1904(true))

Open

func Open(name string) (*File, error)

Opens an existing .xlsx file into memory. The returned workbook can be inspected, modified, and saved again.

OpenReader

func OpenReader(r io.Reader) (*File, error)

Reads an .xlsx workbook from any io.Reader by buffering it in memory.

OpenReaderAt

func OpenReaderAt(r io.ReaderAt, size int64) (*File, error)

Reads an .xlsx workbook from a random-access reader.

File

Represents an in-memory workbook.

Workbook Metadata

func (f *File) Date1904() bool
func (f *File) SetDate1904(enabled bool)
func (f *File) CalcProperties() CalcProperties
func (f *File) SetCalcProperties(props CalcProperties)

Date1904 reports the workbook date system. SetDate1904 switches it for future serialization and formula formatting.

CalcProperties exposes workbook calculation settings such as manual mode or full-calc flags:

type CalcProperties struct {
    Mode           string
    ID             int
    FullCalcOnLoad bool
    ForceFullCalc  bool
    Completed      bool
}

Sheet Access

func (f *File) Sheet(name string) *Sheet
func (f *File) SheetNames() []string
func (f *File) SheetIndex(name string) int

Sheet returns nil if the sheet does not exist. SheetIndex is 0-based and returns -1 when not found.

Sheet Mutation

func (f *File) NewSheet(name string) (*Sheet, error)
func (f *File) DeleteSheet(name string) error
func (f *File) SetSheetName(old, new string) error
func (f *File) SetSheetVisible(name string, visible bool) error

DeleteSheet returns an error if you try to remove the last remaining sheet.

Serialization

func (f *File) SaveAs(name string) error
func (f *File) WriteTo(w io.Writer) error

SaveAs writes to disk. WriteTo serializes to any io.Writer.

Tables and Defined Names

func (f *File) Tables() []Table
func (f *File) DefinedNames() []DefinedName
func (f *File) AddDefinedName(dn DefinedName)
func (f *File) SetDefinedName(dn DefinedName) error
func (f *File) DeleteDefinedName(name string, localSheetID int) error
func (f *File) ResolveDefinedName(name string, sheetIndex int) ([][]Value, error)

Notes:

• Tables() returns workbook tables in workbook order.
• DefinedNames() returns a copy of the current definitions.
• AddDefinedName appends a name but does not replace an existing one.
• SetDefinedName inserts or replaces by name and scope.
• LocalSheetID is -1 for workbook scope and otherwise a 0-based sheet index.
• ResolveDefinedName returns a 2D grid of Value, even for single-cell names.

Formula Graph Helpers

func (f *File) Precedents(sheet, cell string) ([]formula.QualifiedCell, []formula.RangeAddr, error)
func (f *File) DirectDependents(sheet, cell string) ([]formula.QualifiedCell, error)
func (f *File) Recalculate()

Precedents returns the direct point references and range references used by the formula in the target cell. DirectDependents returns the immediate formula cells that read from the given cell. Recalculate forces evaluation of all dirty formulas.

---

Sheet

Represents a single worksheet.

Metadata

func (s *Sheet) Name() string
func (s *Sheet) Visible() bool

Cell Content

func (s *Sheet) SetValue(cell string, v any) error
func (s *Sheet) GetValue(cell string) (Value, error)
func (s *Sheet) SetFormula(cell string, f string) error
func (s *Sheet) GetFormula(cell string) (string, error)

SetValue accepts string, bool, every integer type, float32, float64, time.Time, nil, and werkbook.Value. Setting a plain value clears any existing formula in that cell.

Styling and Layout

func (s *Sheet) SetStyle(cell string, style *Style) error
func (s *Sheet) GetStyle(cell string) (*Style, error)
func (s *Sheet) SetRangeStyle(rangeRef string, style *Style) error
func (s *Sheet) SetColumnWidth(col string, width float64) error
func (s *Sheet) GetColumnWidth(col string) (float64, error)
func (s *Sheet) SetRowHeight(row int, height float64) error
func (s *Sheet) GetRowHeight(row int) (float64, error)

Row and Merge Operations

func (s *Sheet) RemoveRow(row int) error
func (s *Sheet) MergeCell(start, end string) error
func (s *Sheet) MergeCells() []MergeRange

RemoveRow shifts following rows up and updates formula state. MergeCells returns a copy of the registered merged ranges.

Tables and Iteration

func (s *Sheet) Tables() []Table
func (s *Sheet) AddTable(td Table) error
func (s *Sheet) Rows() iter.Seq[*Row]
func (s *Sheet) MaxRow() int
func (s *Sheet) MaxCol() int
func (s *Sheet) PrintTo(w io.Writer)

Rows() iterates rows in ascending order. Rows that only carry a custom height are still included. AddTable validates and registers a worksheet table for writing and structured-reference evaluation.

---

Row

Row.Num

func (r *Row) Num() int

1-based row number.

Row.Height

func (r *Row) Height() float64

Custom row height, or 0 if not set.

Row.Cells

func (r *Row) Cells() []*Cell

All cells in the row, sorted by column number.

---

Cell

Cell.Col

func (c *Cell) Col() int

1-based column number.

Cell.Value

func (c *Cell) Value() Value

Returns the cached cell payload. For formula-aware reads, prefer Sheet.GetValue.

Cell.Formula

func (c *Cell) Formula() string

Formula text, or "".

Cell.Style

func (c *Cell) Style() *Style

Cell style, or nil.

---

Value

Tagged union representing a cell value.

type Value struct {
    Type   ValueType
    Number float64
    String string
    Bool   bool
}

ValueType Constants

const (
    TypeEmpty  ValueType = iota
    TypeNumber
    TypeString
    TypeBool
    TypeError
)

Value.IsEmpty

func (v Value) IsEmpty() bool

Value.Raw

func (v Value) Raw() any

Returns the underlying Go value: float64, string, bool, or nil. For TypeError, inspect Value.String.

---

Style Types

Style

type Style struct {
    Font      *Font
    Fill      *Fill
    Border    *Border
    Alignment *Alignment
    NumFmt    string
    NumFmtID  int
}

Font

type Font struct {
    Name      string
    Size      float64
    Bold      bool
    Italic    bool
    Underline bool
    Color     string
}

Fill

type Fill struct {
    Color string
}

Border

type Border struct {
    Left   BorderSide
    Right  BorderSide
    Top    BorderSide
    Bottom BorderSide
}

type BorderSide struct {
    Style BorderStyle
    Color string
}

BorderStyle

const (
    BorderNone BorderStyle = iota
    BorderThin
    BorderMedium
    BorderThick
    BorderDashed
    BorderDotted
    BorderDouble
)

Alignment

type Alignment struct {
    Horizontal HorizontalAlign
    Vertical   VerticalAlign
    WrapText   bool
}

HorizontalAlign: HAlignGeneral, HAlignLeft, HAlignCenter, HAlignRight

VerticalAlign: VAlignBottom, VAlignCenter, VAlignTop

---

Tables and Names

DefinedName

type DefinedName struct {
    Name         string
    Value        string
    LocalSheetID int // -1 for workbook scope
}

Table

type Table struct {
    SheetName      string
    Name           string
    DisplayName    string
    Ref            string
    Columns        []string
    HeaderRowCount int
    TotalsRowCount int
    AutoFilter     bool
    Style          *TableStyle
}

Ref is an A1 range such as "A1:D10". If Name and DisplayName are both empty, werkbook generates table names automatically.

TableStyle

type TableStyle struct {
    Name              string
    ShowFirstColumn   bool
    ShowLastColumn    bool
    ShowRowStripes    bool
    ShowColumnStripes bool
}

MergeRange

type MergeRange struct {
    Start string
    End   string
}

---

Date Helpers

ExcelSerialToTime

func ExcelSerialToTime(serial float64) time.Time

Converts an Excel serial number using the 1900 date system.

IsDateFormat

func IsDateFormat(numFmt string, numFmtID int) bool

Reports whether a number format string or built-in format ID represents a date/time value.

---

Coordinate Functions

CellNameToCoordinates

func CellNameToCoordinates(cell string) (col, row int, err error)

Converts "B3" to col=2, row=3.

CoordinatesToCellName

func CoordinatesToCellName(col, row int) (string, error)

Converts (2, 3) to "B3".

ColumnNameToNumber

func ColumnNameToNumber(name string) (int, error)

Converts "AA" to 27.

ColumnNumberToName

func ColumnNumberToName(col int) string

Converts 27 to "AA". Returns "" when col is out of range.

RangeToCoordinates

func RangeToCoordinates(ref string) (col1, row1, col2, row2 int, err error)

Parses a range like "A1:C5" into coordinates. Reversed ranges are normalized automatically.

---

Constants

const MaxRows    = 1048576
const MaxColumns = 16384

---

Errors

var ErrInvalidCellRef  = errors.New("invalid cell reference")
var ErrSheetNotFound   = errors.New("sheet not found")
var ErrUnsupportedType = errors.New("unsupported value type")
var ErrEncryptedFile   = ooxml.ErrEncryptedFile