Skip to content

Block Types Overview

HolySheet ships with 57 block types organized into six categories. Each block is a Pydantic v2 model with full type safety and validation.

📊 Quick Reference

📈 Charts (18 types)

Block Type Key Description Key Props
LineChart line_chart Multi-series line chart data, x, y, series, height
AreaChart area_chart Filled area chart data, x, y, series, height
BarChart bar_chart Grouped/stacked bar chart data, x, y, series, height
PieChart pie_chart Pie / donut chart data, name, value, height
ScatterChart scatter_chart Scatter / bubble plot data, x, y, size, category
RadarChart radar_chart Radar / spider chart data, indicators, height
GaugeChart gauge Speedometer gauge value, min, max, thresholds
FunnelChart funnel_chart Conversion funnel data, name, value, height
TreemapChart treemap_chart Hierarchical treemap data, name, value, category
HeatmapChart heatmap_chart 2D heatmap with color gradient data, x, y, value
CandlestickChart candlestick_chart Financial OHLC chart data, x, open, close, low, high
SankeyChart sankey_chart Flow / energy diagram nodes, links
WaterfallChart waterfall_chart Waterfall / bridge chart data, category, value
BoxPlotChart boxplot_chart Statistical box plot data, categories
MapChart map_chart Geographical scatter data, lat, lng, value, name
GanttChart gantt_chart Project timeline / Gantt chart tasks, height
DAGChart dag_chart Directed acyclic graph nodes, edges, layout
CorrelationMatrix correlation_matrix Statistical correlation heatmap matrix, labels, height

📈 KPI & Metrics (4 types)

Block Type Key Description Key Props
KPI kpi Key metric card with delta label, value, unit, delta, status
Metric metric Compact inline metric label, value, unit, icon
StatComparison stat_comparison Side-by-side stat comparison title, items
ProgressBar progress Progress indicator label, value, max, color

📄 Data & Content (14 types)

Block Type Key Description Key Props
DataTable data_table Searchable, paginated table data, columns, searchable, paginated
Markdown markdown Rich text content content
CodeBlock code_block Syntax-highlighted code code, language, title
Image image Image display src, alt, caption, width
Alert alert Callout / notification severity, title, message
Timeline timeline Vertical event timeline events
Callout callout Styled quote / highlight content, author, variant
JsonViewer json_viewer Interactive JSON tree data, collapsed_depth
UserCard user_card Team member card name, role, stats
StatusList status_list Status indicators list items
InfoList info_list Key-value pair display items
Sparkline sparkline Tiny inline chart data, color
Scorecard scorecard Conditional color metric grid data, value_column, thresholds
DataProfile data_profile Auto-EDA column statistics columns

🧱 Layout (8 types)

Block Type Key Description Key Props
Section section Group blocks with heading title, description, children
Columns columns Multi-column grid children, widths, layout
Tabs tabs Tabbed content panels tabs (list of {label, children})
Divider divider Visual separator line label, variant
Accordion accordion Collapsible panels panels
Stepper stepper Process / wizard steps steps, current_step
TagList tag_list Colored tag/badge chips tags
Compare compare Side-by-side comparison container left_children, right_children, mode

🎮 Interactive (9 types)

Block Type Key Description Key Props
Slider slider Interactive slider label, min, max, step, default_value
NumberInput number_input Number input with buttons label, min, max, step
Toggle toggle On/off switch label, description, default_value
Dropdown dropdown Select from options label, options, default_value
TextInput text_input Text / textarea input label, placeholder, multiline
CheckboxGroup checkbox_group Multiple checkboxes label, options, default_values
RadioGroup radio_group Single-select radio buttons label, options, default_value
Embed embed Iframe embed url, height
Video video HTML5 video player src, poster, controls

🧩 How Blocks Work

Every block inherits from Block — a Pydantic v2 BaseModel with a type discriminator:

Basic block usage
from holysheet import Report, KPI, LineChart

report = Report(title="Dashboard", theme="dark")

# Just instantiate and add
report.add(KPI(label="Revenue", value="$1.2M", delta="+12%", status="positive"))
report.add(LineChart(title="Trend", data=my_data, x="date", y="revenue"))  # (1)!

report.export_html("dashboard.html")

Method Chaining

report.add() returns self, so you can chain calls:

report.add(KPI(label="A", value=1)).add(KPI(label="B", value=2))

âž¡ Detailed References

  • KPI & Metrics — KPI cards, compact metrics, stat comparisons
  • Charts — All 18 chart types with data format examples
  • Data & Content — Tables, markdown, code, images, alerts, timelines, scorecards, SQL blocks, narration, AI insights, and Google Sheets
  • Layout — Columns, sections, tabs, dividers, accordions, compare containers
  • Interactive — Sliders, toggles, dropdowns, text inputs, checkboxes, and radio buttons