API Reference
import "github.com/jpoz/werkbook"
File
Represents an Excel workbook (.xlsx).
New
func New(opts ...Option) *FileCreates a new workbook. By default it contains one sheet named “Sheet1”.
Options:
FirstSheet(name string)— override the default first sheet name
wb := werkbook.New()
wb := werkbook.New(werkbook.FirstSheet("Data"))Open
func Open(name string) (*File, error)Opens an existing .xlsx file for reading and writing.
wb, err := werkbook.Open("report.xlsx")File.Sheet
func (f *File) Sheet(name string) *SheetReturns the sheet with the given name, or nil if not found.
File.SheetNames
func (f *File) SheetNames() []stringReturns the names of all sheets in order.
File.NewSheet
func (f *File) NewSheet(name string) (*Sheet, error)Adds a new empty sheet to the workbook.
File.DeleteSheet
func (f *File) DeleteSheet(name string) errorRemoves a sheet. Returns an error if the sheet doesn’t exist or is the last remaining sheet.
File.SaveAs
func (f *File) SaveAs(name string) errorWrites the workbook to the given file path.
File.Recalculate
func (f *File) Recalculate()Forces evaluation of all dirty formula cells in the workbook.
Sheet
Represents a single worksheet.
Sheet.Name
func (s *Sheet) Name() stringSheet.SetValue
func (s *Sheet) SetValue(cell string, v any) errorSets a cell’s value. Accepted types: string, bool, int, int8–int64, uint–uint64, float32, float64, time.Time, nil.
Sheet.GetValue
func (s *Sheet) GetValue(cell string) (Value, error)Returns the cell’s value. Formula cells are evaluated lazily on access.
Sheet.SetFormula
func (s *Sheet) SetFormula(cell string, f string) errorSets a formula (without the leading =).
Sheet.GetFormula
func (s *Sheet) GetFormula(cell string) (string, error)Returns the formula text, or "" if the cell has no formula.
Sheet.SetStyle
func (s *Sheet) SetStyle(cell string, style *Style) errorApplies a style to a single cell.
Sheet.GetStyle
func (s *Sheet) GetStyle(cell string) (*Style, error)Returns the cell’s style, or nil.
Sheet.SetRangeStyle
func (s *Sheet) SetRangeStyle(rangeRef string, style *Style) errorApplies a style to all cells in a range (e.g. "A1:D10").
Sheet.SetColumnWidth
func (s *Sheet) SetColumnWidth(col string, width float64) errorSets the width of a column by letter name (e.g. "A", "BC").
Sheet.GetColumnWidth
func (s *Sheet) GetColumnWidth(col string) (float64, error)Sheet.SetRowHeight
func (s *Sheet) SetRowHeight(row int, height float64) errorSets the height of a row by 1-based row number.
Sheet.GetRowHeight
func (s *Sheet) GetRowHeight(row int) (float64, error)Sheet.Rows
func (s *Sheet) Rows() iter.Seq[*Row]Returns an iterator over all non-empty rows in ascending order.
Sheet.MaxRow
func (s *Sheet) MaxRow() intReturns the highest row number containing data, or 0 if the sheet is empty.
Sheet.MaxCol
func (s *Sheet) MaxCol() intReturns the highest column number containing data, or 0.
Sheet.PrintTo
func (s *Sheet) PrintTo(w io.Writer)Writes a human-readable table to the given writer.
Row
Row.Num
func (r *Row) Num() int1-based row number.
Row.Height
func (r *Row) Height() float64Custom row height, or 0 if not set.
Row.Cells
func (r *Row) Cells() []*CellAll cells in the row, sorted by column number.
Cell
Cell.Col
func (c *Cell) Col() int1-based column number.
Cell.Value
func (c *Cell) Value() ValueCell.Formula
func (c *Cell) Formula() stringFormula text, or "".
Cell.Style
func (c *Cell) Style() *StyleCell 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() boolValue.Raw
func (v Value) Raw() anyReturns the underlying Go value: float64, string, bool, or nil.
Style Types
Style
type Style struct {
Font *Font
Fill *Fill
Border *Border
Alignment *Alignment
NumFmt string // custom format string, e.g. "#,##0.00"
NumFmtID int // built-in format ID (0–163), ignored when NumFmt is set
}Font
type Font struct {
Name string // e.g. "Calibri"
Size float64 // e.g. 11
Bold bool
Italic bool
Underline bool
Color string // 6-char RGB hex, e.g. "FF0000"
}Fill
type Fill struct {
Color string // 6-char RGB hex for solid fill
}Border
type Border struct {
Left, Right, Top, Bottom BorderSide
}
type BorderSide struct {
Style BorderStyle
Color string // 6-char RGB hex
}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
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) stringConverts 27 to "AA".
RangeToCoordinates
func RangeToCoordinates(ref string) (col1, row1, col2, row2 int, err error)Parses a range like "A1:C5" into coordinates. Normalizes reversed ranges.
Constants
const MaxRows = 1048576
const MaxColumns = 16384Errors
var ErrInvalidCellRef = errors.New("invalid cell reference")
var ErrSheetNotFound = errors.New("sheet not found")
var ErrUnsupportedType = errors.New("unsupported value type")