Chemical Formula

Render chemical formulas with colored element symbols, subscripted amounts, superscripted oxidation states, and configurable element ordering.

All formula inputs go through one parser (parse_formula, parse_formula_with_oxidation, parse_composition in matterviz/composition). It accepts nested parentheses and brackets with multipliers (K4[Fe(CN)6], ((CH3)3C)2O), hydrates and adducts joined by ·, ⋅ or * with a leading coefficient (CuSO4·5H2O), fractional amounts (Li0.5Na0.5Cl, Fe.5), charges as ^2+, ^+2, [2-] or a bare ^+/^- placed before or after the count (Fe^3+2O^2-3), Unicode subscripts and superscripts (Fe₂O₃, Fe³⁺) and arbitrary whitespace. Anything else (lowercase symbols, unknown elements, unbalanced or empty parentheses, a bare + without ^ or []) throws an error naming the offending token and its position. Mixed-valence formulas such as Fe^2+Fe^3+2O4 keep one entry per (element, oxidation state) pair.

Basic Usage

Interactive example

svelte<script lang="ts">
  import { Formula } from 'matterviz'
</script>

<div class="demo-controls" style="font-size: 1.5em">
  <Formula formula="H2O" />
  <Formula formula="CO2" />
  <Formula formula="NaCl" />
  <Formula formula="Ca(OH)2" />
  <Formula formula="H2SO4" />
  <Formula formula="C6H12O6" />
</div>

<p>With oxidation states (use <code>^2+</code> or <code>[2+]</code> syntax):</p>

<div class="demo-controls" style="font-size: 1.5em">
  <Formula formula="Fe^2+O" />
  <Formula formula="Fe[3+]2O[2-]3" />
  <Formula formula="Na^+Cl^-" />
  <Formula formula="Ca^2+Cl^-2" />
  <Formula formula="SO4^2-" />
</div>

Element Ordering & Color Schemes

Interactive example

svelte<script lang="ts">
  import { Formula } from 'matterviz'

  let formula = $state(`C6H12O6N2Fe2`)
  let ordering = $state(`original`)
  let color_scheme = $state(`Vesta`)
</script>

<div class="demo-controls">
  <label>Formula: <input type="text" bind:value={formula} style="width: 250px" /></label>
  <label>
    Color Scheme:
    <select bind:value={color_scheme}>
      <option value="Vesta">Vesta</option>
      <option value="Jmol">Jmol</option>
      <option value="Alloy">Alloy</option>
      <option value="Pastel">Pastel</option>
      <option value="Muted">Muted</option>
      <option value="Dark Mode">Dark Mode</option>
    </select>
  </label>
</div>

<div class="demo-controls">
  <strong>Ordering:</strong>
  <label><input type="radio" bind:group={ordering} value="original" /> Original</label>
  <label><input type="radio" bind:group={ordering} value="alphabetical" /> Alphabetical</label>
  <label
    ><input type="radio" bind:group={ordering} value="electronegativity" />
    Electronegativity</label
  >
  <label><input type="radio" bind:group={ordering} value="hill" /> Hill Notation</label>
</div>

<div class="card">
  <Formula {formula} {ordering} {color_scheme} />
</div>

Interactive Click Handlers

Interactive example

svelte<script lang="ts">
  import { Formula } from 'matterviz'

  let clicked_element = $state(null)
  let click_count = $state(0)

  function handle_click(element) {
    clicked_element = element
    click_count++
  }
</script>

<div class="demo-controls" style="font-size: 1.8em">
  <Formula formula="H2O" on_click={handle_click} />
  <Formula formula="Fe[3+]2O[2-]3" on_click={handle_click} />
  <Formula formula="Ca(OH)2" on_click={handle_click} />
  <Formula formula="H2SO4" on_click={handle_click} />
</div>

<div class="card">
  {#if clicked_element}
    <strong>Last clicked:</strong> {clicked_element} (Total: {click_count})
  {:else}
    <em>Click any element symbol above...</em>
  {/if}
</div>

Tooltip Positioning

Interactive example

svelte<script lang="ts">
  import { Formula } from 'matterviz'

  let tooltip_side = $state(`bottom`)
  let tooltip_offset = $state(5)
</script>

<div class="demo-controls">
  <strong>Side:</strong>
  <label><input type="radio" bind:group={tooltip_side} value="top" /> Top</label>
  <label><input type="radio" bind:group={tooltip_side} value="bottom" /> Bottom</label>
  <label><input type="radio" bind:group={tooltip_side} value="left" /> Left</label>
  <label><input type="radio" bind:group={tooltip_side} value="right" /> Right</label>
  <label>
    <strong>Offset:</strong>
    <input type="range" bind:value={tooltip_offset} min="0" max="30" step="5" />
    {tooltip_offset}px
  </label>
</div>

<div class="card">
  <Formula formula="Fe[3+]2O[2-]3" {tooltip_side} {tooltip_offset} style="font-size: 2em" />
</div>

As Different HTML Elements

Use the as prop to render formulas as headings, inline text, etc.:

Interactive example

svelte<script lang="ts">
  import { Formula } from 'matterviz'
</script>

<Formula as="h1" formula="H2O" style="margin: 0.5em 0" />
<Formula as="h2" formula="CO2" style="margin: 0.5em 0" />

<p style="font-size: 1.1em">
  Inline formulas work too:
  <Formula as="span" formula="NaCl" />
  and
  <Formula as="strong" formula="H2SO4" />
  in regular text.
</p>

Structured Input & Amount Formatting

Use OxiComposition objects and customize number formatting:

Interactive example

svelte<script lang="ts">
  import { Formula } from 'matterviz'

  const iron_oxide = {
    Fe: { amount: 2, oxidation_state: 3 },
    O: { amount: 3, oxidation_state: -2 },
  }

  let amount_format = $state(`.3~s`)
</script>

<div class="demo-controls" style="gap: 2em">
  <span>
    From object:
    <Formula formula={iron_oxide} ordering="alphabetical" style="font-size: 2em" />
  </span>
  <label>
    Amount Format:
    <select bind:value={amount_format}>
      <option value=".3~s">Compact (default)</option>
      <option value=".2f">2 decimals</option>
      <option value=".0f">Integer</option>
      <option value=".1f">1 decimal</option>
    </select>
    <Formula formula="H2.567O1.234C0.891" {amount_format} style="font-size: 1.5em" />
  </label>
</div>

Real-World Compounds

Interactive example

svelte<script lang="ts">
  import { Formula } from 'matterviz'

  const categories = {
    'Battery Materials': [
      { name: `LiFePO₄ (LFP)`, formula: `LiFePO4` },
      { name: `LiCoO₂ (LCO)`, formula: `LiCoO2` },
      { name: `NMC 111`, formula: `LiNi0.33Mn0.33Co0.33O2` },
    ],
    Minerals: [
      { name: `Quartz`, formula: `SiO2` },
      { name: `Magnetite`, formula: `Fe3O4` },
      { name: `Calcite`, formula: `CaCO3` },
    ],
    Organic: [
      { name: `Glucose`, formula: `C6H12O6` },
      { name: `Caffeine`, formula: `C8H10N4O2` },
      { name: `Ethanol`, formula: `C2H6O` },
    ],
  }
</script>

{#each Object.entries(categories) as [category, compounds] (category)}
  <h3 style="margin: 1.5em 0 0.5em; font-size: 1.1em">{category}</h3>
  <div class="grid">
    {#each compounds as { name, formula } (formula)}
      <div>
        <Formula
          {formula}
          ordering={category === 'Organic' ? 'hill' : 'electronegativity'}
          style="font-size: 1.3em"
        />
        <small>{name}</small>
      </div>
    {/each}
  </div>
{/each}

Interactive Builder

Interactive example

svelte<script lang="ts">
  import { Formula } from 'matterviz'

  let next_id = 2
  let elements = $state([
    { id: 0, symbol: `Fe`, amount: 2, oxidation: 3 },
    { id: 1, symbol: `O`, amount: 3, oxidation: -2 },
  ])

  const formula_obj = $derived.by(() => {
    const obj = {}
    for (const { symbol, amount, oxidation } of elements) {
      obj[symbol] = { amount, oxidation_state: oxidation }
    }
    return obj
  })
</script>

<button
  onclick={() =>
    (elements = [...elements, { id: next_id++, symbol: `H`, amount: 1, oxidation: 0 }])}
>
  Add Element
</button>

{#each elements as element (element.id)}
  <div class="row">
    <input type="text" bind:value={element.symbol} style="width: 50px" placeholder="El" />
    <input
      type="number"
      bind:value={element.amount}
      step="0.1"
      style="width: 70px"
      placeholder="Amt"
    />
    <input type="number" bind:value={element.oxidation} style="width: 60px" placeholder="Ox" />
    <button
      onclick={() => (elements = elements.filter((element_2) => element_2.id !== element.id))}
    >
      ×
    </button>
  </div>
{/each}

<div class="card">
  <Formula formula={formula_obj} />
</div>
Props of Formula