Class XlsxFormat
- Namespace
- DocToolkit
- Assembly
- DocToolkit.Xlsx.dll
The presentation Format(byte[], string, XlsxFormat) applies to a sheet: a bold header row, a freeze position, auto-fitted or explicit column widths, a number format per column, an autofilter, conditional formats, data validations, tables, a print setup, merged cells, hyperlinks and comments.
public sealed class XlsxFormat- Inheritance
-
XlsxFormat
- Inherited Members
Remarks
The boundary here is a CLOSED vocabulary, not a small one — and that is a change. This type used to say the smallness was the design, and excluded conditional rules by name. It was reversed deliberately on 2026-08-26, because "small" stops being a boundary the moment anything is added, while "closed" survives the question.
| in | out |
|---|---|
| a vocabulary this library can enumerate, measure and guarantee — six rule conditions, five validation kinds, four highlights, four table style tiers, a freeze position, a column width, a merged range, a hyperlink, a comment | an open one it would have to own forever — arbitrary fonts, borders, fills, colour scales, icon sets |
XlsxHighlight is the test case for that line: four named intents can be enumerated and guaranteed, a colour picker cannot. If what you need cannot be expressed as a closed set, the original answer still stands — use ClosedXML directly rather than have this package grow a second, worse styling API in front of it.
Immutable, with With… methods returning a new instance — the same shape as
PageSetup.
Properties
AutoFilter
Whether the sheet's used range carries an autofilter.
public bool AutoFilter { get; }Property Value
Remarks
A sheet with no data has no used range, so it gets no filter rather than an error.
AutoFitColumns
Whether each column is widened to fit its contents.
public bool AutoFitColumns { get; }Property Value
BoldHeaderRow
Whether the first row is bold.
public bool BoldHeaderRow { get; }Property Value
ColumnNumberFormats
Number formats by column letter — "B" to "#,##0.00", for instance. Empty
unless set.
public IReadOnlyDictionary<string, string> ColumnNumberFormats { get; }Property Value
Remarks
Keyed by column letter rather than index, because that is how a spreadsheet's user
refers to a column and how ReadCell(byte[], string, string)
already addresses cells. Case-insensitive: "b" and "B" are the same column.
The strings are Excel's own number-format codes, passed through unaltered. DocToolkit does not validate or translate them — inventing a format language in front of a standard one would be a second thing to learn and a second thing to get wrong.
ColumnWidths
An explicit width per column letter. Empty unless set.
public IReadOnlyDictionary<string, double> ColumnWidths { get; }Property Value
Remarks
Applied after AutoFitColumns, so a named column takes this width while the rest stay auto-fitted. A specific instruction beats a blanket one.
Comments
The comments to add, in the order given. Empty unless set.
public IReadOnlyList<XlsxComment> Comments { get; }Property Value
FreezeAt
Where the sheet is frozen, or null if it is not.
public XlsxFreeze? FreezeAt { get; }Property Value
FreezeHeaderRow
Whether the first row stays visible while the rest of the sheet scrolls.
public bool FreezeHeaderRow { get; }Property Value
Remarks
Derived from FreezeAt rather than stored, so the two cannot disagree. Freezing anywhere else makes this false, which is the honest answer rather than a stale one.
Hyperlinks
The hyperlinks to add, in the order given. Empty unless set.
public IReadOnlyList<XlsxHyperlink> Hyperlinks { get; }Property Value
MergedRanges
The ranges to merge, in the order given. Empty unless set.
public IReadOnlyList<string> MergedRanges { get; }Property Value
None
Applies nothing. The starting point for building a format up.
public static XlsxFormat None { get; }Property Value
PageSetup
The sheet's print setup, or null if none is set.
public XlsxPageSetup? PageSetup { get; }Property Value
Report
The three settings that make a generated sheet readable: a bold header row, that row frozen so it stays visible while scrolling, and columns wide enough to show their contents.
public static XlsxFormat Report { get; }Property Value
Remarks
A preset rather than three calls because it is the answer to the question people actually have — "make this look like a report" — and because leaving it out would mean every caller rediscovering the same three settings.
Rules
The conditional formats to apply, in the order given. Empty unless set.
public IReadOnlyList<XlsxRule> Rules { get; }Property Value
Sparklines
The sparklines to draw. Empty unless WithSparkline(XlsxSparkline) was called.
public IReadOnlyList<XlsxSparkline> Sparklines { get; }Property Value
Tables
The tables to create, in the order given. Empty unless set.
public IReadOnlyList<XlsxTable> Tables { get; }Property Value
Validations
The data validations to apply, in the order given. Empty unless set.
public IReadOnlyList<XlsxValidation> Validations { get; }Property Value
Remarks
Overlapping ranges are consolidated by the library beneath, and the LATER one wins.
Measured: a whole-number validation on B2:B10 followed by a list on B5:B15
leaves the first covering only B2:B4; the same range twice leaves only the second.
Rules does not behave this way — six conditional formats over two ranges
stay six — so do not reason from one to the other.
Methods
WithAutoFilter(bool)
Returns a copy that puts an autofilter on the sheet's used range.
public XlsxFormat WithAutoFilter(bool enabled = true)Parameters
enabledboolWhether to apply one.
Returns
WithAutoFitColumns(bool)
Returns a copy with AutoFitColumns set.
public XlsxFormat WithAutoFitColumns(bool autoFit = true)Parameters
autoFitboolWhether each column is widened to fit its contents.
Returns
WithBoldHeaderRow(bool)
Returns a copy with BoldHeaderRow set.
public XlsxFormat WithBoldHeaderRow(bool bold = true)Parameters
boldboolWhether the first row is bold.
Returns
WithColumnWidth(string, double)
Returns a copy that gives column an explicit width.
public XlsxFormat WithColumnWidth(string column, double width)Parameters
columnstringA column letter, such as
"A". Case-insensitive.widthdoubleThe width in Excel's character units. Must be positive.
Returns
Remarks
Applied after AutoFitColumns, so this wins for the column it names while the rest stay auto-fitted.
Exceptions
- ArgumentNullException
columnis null.- ArgumentException
columnis not one or more letters.- ArgumentOutOfRangeException
widthis not positive.
WithComment(XlsxComment)
Returns a copy carrying one more comment.
public XlsxFormat WithComment(XlsxComment comment)Parameters
commentXlsxCommentThe comment to add.
Returns
Exceptions
- ArgumentNullException
commentis null.
WithFreezeAt(int, int)
Returns a copy frozen at a position.
public XlsxFormat WithFreezeAt(int row, int column)Parameters
Returns
Remarks
(0, 0) is refused: it would freeze nothing while making FreezeAt report a
value, which is two spellings of one state. Use WithFrozenHeaderRow(bool) with false
to freeze nothing. Rows-only and columns-only are both legal.
Exceptions
- ArgumentOutOfRangeException
Either is negative, or both are zero.
WithFrozenHeaderRow(bool)
Returns a copy that freezes row 1, or that freezes nothing.
public XlsxFormat WithFrozenHeaderRow(bool frozen = true)Parameters
frozenboolWhether to freeze row 1.
Returns
Remarks
frozen false clears whatever freeze is set, not only a header-row
one — the state is a single position rather than two independent switches, and a method that
did something different depending on the current value would be worse than one that is blunt
about it.
WithHyperlink(XlsxHyperlink)
Returns a copy carrying one more hyperlink.
public XlsxFormat WithHyperlink(XlsxHyperlink hyperlink)Parameters
hyperlinkXlsxHyperlinkThe hyperlink to add.
Returns
Exceptions
- ArgumentNullException
hyperlinkis null.
WithMergedCells(string)
Returns a copy carrying one more merged range.
public XlsxFormat WithMergedCells(string range)Parameters
rangestringThe cells to merge, such as
A1:C1.
Returns
Exceptions
- ArgumentNullException
rangeis null.- ArgumentException
rangeis blank or names a sheet.
WithNumberFormat(string, string)
Returns a copy that formats column with numberFormat.
public XlsxFormat WithNumberFormat(string column, string numberFormat)Parameters
columnstringA column letter, such as
"B". Case-insensitive.numberFormatstringAn Excel number-format code, such as
"#,##0.00"or"yyyy-mm-dd".
Returns
Exceptions
- ArgumentNullException
Either argument is null.
- ArgumentException
columnis not one or more letters, ornumberFormatis blank. Checked here rather than at apply time so a typo fails where it was written.
WithPageSetup(XlsxPageSetup)
Returns a copy carrying a print setup.
public XlsxFormat WithPageSetup(XlsxPageSetup pageSetup)Parameters
pageSetupXlsxPageSetupThe print setup to apply.
Returns
Exceptions
- ArgumentNullException
pageSetupis null.
WithRule(XlsxRule)
Returns a copy carrying one more conditional format.
public XlsxFormat WithRule(XlsxRule rule)Parameters
ruleXlsxRuleThe rule to add.
Returns
Exceptions
- ArgumentNullException
ruleis null.
WithSparkline(XlsxSparkline)
Returns a copy carrying one more sparkline.
public XlsxFormat WithSparkline(XlsxSparkline sparkline)Parameters
sparklineXlsxSparklineThe sparkline to draw.
Returns
Exceptions
- ArgumentNullException
sparklineis null.
WithTable(XlsxTable)
Returns a copy carrying one more table.
public XlsxFormat WithTable(XlsxTable table)Parameters
tableXlsxTableThe table to add.
Returns
Remarks
Do not also call WithAutoFilter(bool) over a range that overlaps this table. A ClosedXML table already carries its own autofilter, and applying the sheet-wide one on top of an overlapping table range throws DocumentConversionException at Format(byte[], string, XlsxFormat) time — measured directly, not merely likely. Use one or the other over the same cells.
Exceptions
- ArgumentNullException
tableis null.
WithValidation(XlsxValidation)
Returns a copy carrying one more data validation.
public XlsxFormat WithValidation(XlsxValidation validation)Parameters
validationXlsxValidationThe validation to add.
Returns
Exceptions
- ArgumentNullException
validationis null.