API Reference

Complete reference for all Sone components, methods, and utilities.

Core Components

Column

Creates a vertical flex container.

function Column(...children: SoneNode[]): ColumnNode

Methods:

All Layout Props methods
Standard flex properties with flexDirection: "column" by default

Example:

Column(
  Text("First"),
  Text("Second")
).gap(10).padding(20)

Row

Creates a horizontal flex container.

function Row(...children: SoneNode[]): RowNode

Methods:

All Layout Props methods
Standard flex properties with flexDirection: "row" by default

Example:

Row(
  Text("Left"), 
  Text("Right")
).justifyContent("space-between")

Text

Displays rich text content.

function Text(...children: Array<SpanNode | string | undefined | null>): TextNode

Text-specific Methods:

align(value: "left" | "center" | "right" | "justify"): TextNode
lineHeight(value: number): TextNode
nowrap(): TextNode
wrap(value?: boolean): TextNode
indent(value: number): TextNode
hangingIndent(value: number): TextNode
autofit(value?: boolean): TextNode

Text Styling Methods:

All Span Props methods
All Layout Props methods

Example:

Text("Hello ", Span("World").color("blue"))
  .size(16)
  .align("center")
  .lineHeight(1.4)

Span

Inline text styling within Text components.

function Span(children: string): SpanNode

Methods:

All Span Props methods

Example:

Span("Important text")
  .color("red")
  .weight("bold")
  .underline()

TextDefault

Applies default text styling to child components.

function TextDefault(...children: SoneNode[]): TextDefaultNode

Methods:

All Span Props methods (except layout properties)
Text layout methods: nowrap(), wrap(), lineHeight(), align(), indent()

Example:

TextDefault(
  Text("Inherits styling"),
  Text("Also inherits")
)
.font("Arial", "sans-serif")
.size(14)
.color("black")

Photo

Displays images with scaling and transformation options.

function Photo(src: string | Uint8Array): PhotoNode

Photo-specific Methods:

scaleType(value: "cover" | "contain" | "fill", alignment?: number | "start" | "center" | "end"): PhotoNode
preserveAspectRatio(value?: boolean): PhotoNode
flipHorizontal(value?: boolean): PhotoNode
flipVertical(value?: boolean): PhotoNode
fill(value: ColorValue): PhotoNode

Methods:

All Layout Props methods

Example:

Photo("image.jpg")
  .size(200, 150)
  .scaleType("cover", "center")
  .rounded(8)

Path

Renders SVG path graphics.

function Path(d: string): PathNode

Path-specific Methods:

stroke(value: ColorValue): PathNode
strokeWidth(value: number): PathNode
strokeLineCap(value: "butt" | "round" | "square"): PathNode
strokeLineJoin(value: "miter" | "round" | "bevel"): PathNode
strokeMiterLimit(value: number): PathNode
strokeDashArray(...values: number[]): PathNode
strokeDashOffset(value: number): PathNode
fill(value: ColorValue): PathNode
fillOpacity(value: number): PathNode
fillRule(value: "evenodd" | "nonzero"): PathNode
scalePath(value: number): PathNode

Methods:

All Layout Props methods

Example:

Path("M 10 10 L 50 50 Z")
  .fill("red")
  .stroke("black")
  .strokeWidth(2)

Table Components

Table

Creates a table layout container.

function Table(...children: TableRowNode[]): TableNode

Table-specific Methods:

spacing(...values: number[]): TableNode

Methods:

All Layout Props methods

TableRow

Represents a table row.

function TableRow(...children: Array<TextDefaultNode | TableCellNode | null | undefined>): TableRowNode

Methods:

All Layout Props methods

TableCell

Individual table cell.

function TableCell(...children: SoneNode[]): TableCellNode

TableCell-specific Methods:

colspan(value: number): TableCellNode
rowspan(value: number): TableCellNode

Methods:

All Layout Props methods

Example:

Table(
  TableRow(
    TableCell(Text("Header 1")),
    TableCell(Text("Header 2"))
  ).bg("gray"),
  TableRow(
    TableCell(Text("Data 1")),
    TableCell(Text("Data 2"))
  )
).spacing(5)

Layout Props

Common layout properties available on most components:

Flexbox Properties

alignContent(value: AlignContent): T
alignItems(value: AlignItems): T
alignSelf(value: AlignItems): T
justifyContent(value: JustifyContent): T
direction(value: FlexDirection): T
wrap(value: "wrap" | "nowrap" | "wrap-reverse"): T
flex(value: number): T
grow(value: number): T
shrink(value: number): T
basis(value: number | "auto" | string): T

Spacing

gap(value: number): T
rowGap(value: number): T
columnGap(value: number): T
padding(all: number): T
padding(topBottom: number, leftRight: number): T
padding(top: number, leftRight: number, bottom: number): T
padding(top: number, right: number, bottom: number, left: number): T
paddingTop(value: number): T
paddingRight(value: number): T
paddingBottom(value: number): T
paddingLeft(value: number): T
margin(...): Similar overloads as padding
marginTop(value: number): T
marginRight(value: number): T
marginBottom(value: number): T
marginLeft(value: number): T

Sizing

width(value: number | "auto" | string): T
height(value: number | "auto" | string): T
size(width: number, height?: number): T
minWidth(value: number | string): T
maxWidth(value: number | string): T
minHeight(value: number | string): T
maxHeight(value: number | string): T
aspectRatio(value: number): T

Positioning

position(value: "static" | "relative" | "absolute"): T
top(value: number | string): T
right(value: number | string): T
bottom(value: number | string): T
left(value: number | string): T
inset(value: number | string): T

Visual Styling

bg(...values: ColorValue | PhotoNode | GradientNode[]): T
background(...values: ColorValue | PhotoNode | GradientNode[]): T
opacity(value: number): T
borderWidth(...): CSS-like shorthand overloads
borderColor(value: ColorValue): T
rounded(...values: number[]): T
borderRadius(...values: number[]): T
cornerSmoothing(value: number): T
corner(value: "cut" | "round"): T
shadow(...values: string[]): T

Transforms

rotate(value: number): T
scale(value: number): T
scale(x: number, y: number): T
translateX(value: number): T
translateY(value: number): T

Filters

blur(value: number): T
brightness(value: number): T
contrast(value: number): T
grayscale(value: number): T
saturate(value: number): T
sepia(value: number): T
invert(value: number): T
huerotate(value: number): T

Utility

apply(value: LayoutProps): T
tag(value: string): T

Span Props

Text styling properties for Span and Text components:

Font Properties

size(value: number): T
font(...values: string[]): T
weight(value: "normal" | "bold" | "lighter" | "bolder" | string | number): T
style(value: "normal" | "italic" | "oblique"): T
color(value: ColorValue | GradientNode[]): T

Text Spacing

letterSpacing(value: number): T
wordSpacing(value: number): T

Text Effects

dropShadow(...values: string[]): T
strokeColor(value: ColorValue): T
strokeWidth(value: number): T
offsetY(value: number): T

Text Decorations

underline(value?: number): T
underlineColor(value?: ColorValue): T
lineThrough(value?: number): T
lineThroughColor(value?: ColorValue): T
overline(value?: number): T
overlineColor(value?: ColorValue): T
highlight(value?: ColorValue): T

Rendering Functions

sone()

Main rendering function for Node.js.

function sone(node: SoneNode, config?: SoneRenderConfig): {
  jpg: (quality?: number, options?: ExportOptions) => Promise<Buffer>
  png: (options?: ExportOptions) => Promise<Buffer>
  svg: (options?: ExportOptions) => Promise<Buffer>
  pdf: (options?: ExportOptions) => Promise<Buffer>
  webp: (options?: ExportOptions) => Promise<Buffer>
  raw: (options?: ExportOptions) => Promise<Buffer>
  canvas: () => Promise<Canvas>
  canvasWithMetadata: () => Promise<{ canvas: Canvas; metadata: any }>
}

Export Methods:

jpg(quality?, options?) - Export as JPEG
png(options?) - Export as PNG
svg(options?) - Export as SVG
pdf(options?) - Export as PDF
webp(options?) - Export as WebP
raw(options?) - Export as raw buffer
canvas() - Get Canvas instance
canvasWithMetadata() - Get Canvas with layout metadata

render()

Generic render function for custom renderers.

function render<T>(
  node: SoneNode, 
  renderer: SoneRenderer, 
  config?: SoneRenderConfig
): Promise<T>

Font Management

Font

Font loading and management utility.

const Font = {
  load(name: string, source: string | string[]): Promise<void>
  unload(name: string): Promise<void>
  has(name: string): boolean
}

Methods:

Font.load(name, source) - Load and register font
Font.unload(name) - Unload font (Node.js only)
Font.has(name) - Check if font is loaded

Utilities

qrcode()

Generate QR codes.

function qrcode(
  data: string,
  options?: {
    size?: number
    margin?: number
    errorCorrectionLevel?: "L" | "M" | "Q" | "H"
  }
): PhotoNode

Example:

qrcode("https://example.com")
  .size(200)
  .bg("white")
  .rounded(8)

Type Definitions

Color Types

type ColorValue = 
  | keyof typeof colors    // Named colors: "red", "blue", etc.
  | "transparent"
  | string                 // CSS colors: "#ff0000", "rgb(255,0,0)", etc.

type GradientNode = {
  // Parsed gradient object from gradient-parser
}

Layout Types

type FlexDirection = "column" | "column-reverse" | "row" | "row-reverse"
type AlignItems = "flex-start" | "flex-end" | "center" | "stretch" | "baseline"
type JustifyContent = "flex-start" | "flex-end" | "center" | "space-between" | "space-around" | "space-evenly"
type AlignContent = "flex-start" | "flex-end" | "center" | "stretch" | "space-between" | "space-around" | "space-evenly"

Font Types

type FontValue = "sans-serif" | "serif" | "monospace" | string

Node Types

type SoneNode = 
  | ColumnNode 
  | RowNode 
  | TextNode 
  | TextDefaultNode
  | PhotoNode 
  | PathNode 
  | TableNode 
  | TableRowNode 
  | TableCellNode
  | null 
  | undefined

Configuration

SoneRenderConfig

interface SoneRenderConfig {
  width?: number          // Canvas width
  height?: number         // Canvas height
  devicePixelRatio?: number  // Pixel density
  debug?: {
    layout?: boolean      // Debug layout
    text?: boolean        // Debug text rendering
  }
}

Platform-Specific APIs

Node.js Only

Features only available in Node.js environment:

Full font loading from file paths
All export formats (PDF, WebP, etc.)
Font unloading
Buffer input for images

Browser Limitations

When using in browsers:

Custom renderer required
Limited font loading capabilities
Image loading restrictions due to CORS
No PDF/WebP export without additional libraries

Error Handling

Common error scenarios:

try {
  const result = await sone(document).jpg();
} catch (error) {
  if (error.message.includes('Font not found')) {
    // Handle font loading issues
  }
  if (error.message.includes('Image load failed')) {
    // Handle image loading issues
  }
}

Performance Tips

Use tag() for debugging complex layouts
Preload fonts at application startup
Cache rendered results when possible
Optimize image sizes before use
Use simple paths for better Path performance

API Reference

On this page