URL Integrations

Instacalc can be used as a “stateless” tool where the calculation is stored entirely in the URL. This makes it incredibly easy to share logic without ever needing to “save” a file to a database.

GitHub Integration

Instacalc features a “Magic URL” integration with GitHub. You can load any calculator file (.ic, .md, or .txt) or even an entire directory directly from GitHub.

How It Works

Paste any GitHub URL after instacalc.com/ and it becomes a live calculator.

GitHub: https://github.com/kazad/instacalc/blob/main/demo/sample.ic
Instacalc: instacalc.com/https://github.com/kazad/instacalc/blob/main/demo/sample.ic

Just put instacalc.com/ in front of the GitHub link — that’s it.

What you can open:

Files: instacalc.com/<github file URL> — renders as a live calculator
Folders: instacalc.com/<github tree URL> — gallery of all calculators in the directory
Repos: instacalc.com/github.com/owner/repo — browse all calculators in the repo

Caching & Refreshing

Instacalc caches GitHub content for 5 minutes to stay within API limits. If you’ve just pushed changes:

Add ?fresh to the URL to bypass the cache
Or hover over the GitHub icon and click Refresh
Automatic Updates: When you update the file on GitHub, the calculator updates within 5 minutes (or instantly with ?fresh).
Remixable: Anyone can open the link and start editing. If they want to save their changes, they can save it as a new Instacalc.

Data Links (Stateless Calcs)

Instacalc is designed to be super URL-friendly. You can encode calculator rows directly in the URL — creating “stateless” calculators that live entirely in the link, with no account or saved file needed. This is perfect for dynamic links, spreadsheets, or simple scripts.

The Send a copy button emits the readable path form below. Every format here is plain, human-readable text — Instacalc never base64-encodes your calc. A data link is something you can read, edit, and even type by hand.

The Formats at a Glance

Format	Example	When it’s used
Path	`instacalc.com/qty=5;price=99;qty*price`	The default. What Send a copy emits.
Path + title	`instacalc.com/Unit_Price;qty=5;qty*99`	A plain-text first segment becomes the title.
Explicit formula	`instacalc.com/=sin(x);cos(x);tan(x)`	Leading `=` says “all rows, no title”.
Bare math	`instacalc.com/sqrt(2)` · `instacalc.com/(2+3)*4`	Single expression, no `=` needed.
Hash	`instacalc.com/#bill=50;tip=bill*0.20`	Fragment form (`#…`). Stays out of server logs.
Legacy `?d=`	`instacalc.com/?d=%7B%22rows%22...%7D`	Old JSON form — read-only, kept working forever.

Path Form (the default)

Format: instacalc.com/<row1>;<row2>;<row3>

Delimiters: Use ; or | to separate rows. | is often easier to type and read in URLs.

To keep URLs clean and avoid ugly %20 encoding, Instacalc uses Underscore Normalization:

Underscores become Spaces: my_variable in the URL becomes my variable in the calculator.
Double Underscores are Literals: Use __ if you actually need a literal underscore in your text.
Title Support: If the first segment is plain text (a few words, no math operators), it becomes the title.

Example: A “Clean” Link instacalc.com/Unit_Price;qty=5;price=99;qty*price

Title: Unit Price
Rows: qty=5, price=99, qty*price

Example: Chained Operations

In a URL, | separates rows, so chain array operations within a single row using dot-chaining (.map().sum) instead:

instacalc.com/[1,2,3].map(x=>x*10).sum

Output: 60

Explicit Formula (`=` prefix)

Start the URL with = to say “every segment is a row — don’t treat the first one as a title.” Useful when your first row reads like a label but is really a calculation.

instacalc.com/=sin(x);cos(x);tan(x)

Rows: sin(x), cos(x), tan(x) (no title promoted)

Bare Math (no `=` needed)

A single math expression just works — a parenthesis or a known function (sin, sqrt, log10, …) is enough of a signal.

instacalc.com/sqrt(2) · instacalc.com/(2+3)*4

Hash Form (`#`)

The same encoding can ride in the URL fragment instead of the path:

instacalc.com/#bill=50|tip=bill*0.20

Because everything after # never leaves the browser, the hash form keeps your calc out of server logs and referrer headers. (Note: a hash that’s just a name — #team-budget — opens a live room instead.)

Legacy `?d=` (read-only)

Older links used a ?d=<url-encoded-JSON> data parameter. Those still load forever, but new links use the readable path form above — it’s shorter, typeable, and editable.

URL Encoding Tips

No base64. Data links are always readable text — read them, tweak a number, share again.
+ is treated as addition, not a space.
Use _ for spaces (and __ for a literal underscore) to keep the URL human-readable, or use camelCase to avoid spaces entirely.
; and | separate rows — to use one inside a row, wrap that part in [...] (e.g. a [label|action] pill) or percent-encode it (%7C, %3B).
Length limit: ~16,000 characters. Plenty for any real calc; longer payloads are rejected.

URL Parameter Overrides

You can pass custom values into any calculator (shared, GitHub, or data link) via the query string. This is useful for “pre-filling” a calculator with specific numbers.

Matching rows (e.g., price = 10) will have their values replaced by the ones in the URL.

Supported Formats

Standard Query Params: instacalc.com/12345?price=99&qty=5
Semicolon Separated (Compact): instacalc.com/12345?price=99;qty=5
Pipe Separated: instacalc.com/12345?price=99|qty=5

Combined Example (Data Link + Overrides): instacalc.com/qty=1;price=10;qty*price?qty=5

This opens a data link with qty=1, but immediately overrides it to qty=5.

Live Workspaces (Collaborative)

Want to work with someone in real-time? Use a Hash Room.

Format: instacalc.com/#<room-name>

Example: instacalc.com/#our-trip-budget

Real-time: Everyone at the same URL sees updates instantly.
Ephemeral: These rooms are “live” workspaces. They are not indexed by search engines.
No Login Required: Just pick a unique room name and share the link.
Read/Write: Anyone with the URL can read and write to the workspace.