Structure

Bi2Zr2O8-Fm3m.json

No structure provided

🔷 crystal🧬 molecule CIF EXTXYZ GZ JSON POSCAR XYZ

🔷 AgI-fq978185p-phono3py.yaml.gz

🔷 BaTiO3-tetragonal.poscar

🔷 BeO-zw12zc18p-phono3py.yaml.gz

🔷 Bi2Zr2O8-Fm3m.json

🔷 Cu-FCC.json

🔷 Fe-BCC.json

🔷 Li10GeP2S12.cif

🔷 Li4Fe3Mn1(PO4)4.cif

🔷 Li8Fe2NiCoO8.cif

🔷 LiFePO4.cif

🔷 MgNiF6.cif

🔷 NaCl-cubic.poscar

🔷 P24Ru4H252C296S24N16.cif

🔷 PF-sd-1601634.cif

🔷 Po-simple-cubic.json

🔷 TiO2.cif

🔷 TlBiSe2-highly-oblique-cell.json

🔷 aviary-CuF3K-triolith.poscar

🔷 mof-issue-127.cif

🔷 mp-1.json

🔷 mp-10018-Ac1-cubic.json

🔷 mp-1183057-Ac3-trigonal.json.gz

🔷 mp-1183085-Ac4Mg2-orthorhombic.json

🔷 mp-1183089-Ac4Mg2-monoclinic.json

🔷 mp-1204603.json

🔷 mp-1207297-Ac2Br2O1-tetragonal.json

🔷 mp-1229155.json

🔷 mp-1229168.json

🔷 mp-1234.json

🔷 mp-12712.json

🔷 mp-19017.json.gz

🔷 mp-2.json

🔷 mp-686119-Ag13Bi14I56-triclinic.json

🔷 mp-7000-optimade.json

🔷 mp-756175.json

🔷 mp-862690-Ac4-hexagonal.json

🧬 nested-Hf36Mo36Nb36Ta36W36-hcp-mace-omat.json.gz

🔷 quartz-alpha.cif

🔷 quartz.extxyz

🔷 scientific-notation.poscar

🔷 selective-dynamics.poscar

🔷 vasp4-format.poscar

🧬 C2HO-scientific-notation.xyz

🧬 C5-extra-data.xyz

🧬 benzene.json

🧬 cyclohexane.xyz

🧬 ethanol.json

🧬 methane.json

🧬 methyl.json

🧬 water.json

svelte<script lang="ts">
  import { page } from '$app/state'
  import { goto } from '$app/navigation'
  import { browser } from '$app/environment'
  import { Structure } from 'matterviz'
  import Select from 'svelte-multiselect'
  import { structure_files } from '$site/structures'
  import { molecule_files } from '$site/molecules'
  import FilePicker from '$lib/FilePicker.svelte'
  import { decode_url_safe_base64, get_electro_neg_formula } from '$lib'

  let current_filename = $state(`Bi2Zr2O8-Fm3m.json`)
  // Inline structure data from URL hash (used by ferrox render CLI)
  let hash_structure_string = $state<string>()

  const all_files = [...structure_files, ...molecule_files]
  function get_file_url(filename: string): string {
    const file_info = all_files.find((file) => file.name === filename)
    return file_info?.url || `/structures/${filename}`
  }

  $effect(() => {
    if (!browser) return
    // Support #structure=BASE64 for CLI-generated links (ferrox render).
    // Must use window.location.hash since SvelteKit's page.url.hash is always empty.
    const hash = window.location.hash
    if (hash.startsWith(`#structure=`)) {
      const raw = hash.slice(`#structure=`.length)
      const decoded = decode_url_safe_base64(raw)
      if (decoded !== undefined) {
        hash_structure_string = decoded
        current_filename = `CLI structure`
      } else {
        console.error(`Failed to decode base64 structure from URL hash`)
      }
      return
    }
    const file = page.url.searchParams.get(`file`)
    if (file && file !== current_filename) current_filename = file
  })
</script>

<Structure
  data_url={hash_structure_string ? undefined : get_file_url(current_filename)}
  structure_string={hash_structure_string}
  on_file_load={(data: { filename: string }) => {
    current_filename = data.filename
    page.url.searchParams.set(`file`, current_filename)
    goto(`${page.url.pathname}?${page.url.searchParams.toString()}`, {
      replaceState: true,
      keepFocus: true,
      noScroll: true,
    })
  }}
>
  <h3 style="position: absolute; margin: 1ex 1em; font-family: monospace; z-index: 1">
    {current_filename}
  </h3>
</Structure>

<FilePicker
  files={all_files}
  show_category_filters
  style="margin-block: 2em"
/>

Explicit Bond Orders

MatterViz accepts explicit bond metadata on structure.properties.bonds. The viewer still computes normal proximity bonds, but any matching explicit entries set the rendered order, and explicit-only entries are added to the scene.

In Edit Bonds mode, Add is the safe default: click two atoms to add or restore a bond without risking accidental deletion. Switch to Delete to remove existing bonds by clicking them. Use the order selector for new bonds, or open a bond’s context menu to update an existing bond order interactively.

svelte<script lang="ts">
  import { Structure } from 'matterviz'
  import type { Molecule } from 'matterviz'

  const bond_order_playground: Molecule = {
    id: `explicit-bond-order-playground`,
    sites: [
      {
        species: [{ element: `C`, occu: 1, oxidation_state: 0 }],
        abc: [-2.4, 0, 0],
        xyz: [-2.4, 0, 0],
        label: `C1`,
        properties: {},
      },
      {
        species: [{ element: `C`, occu: 1, oxidation_state: 0 }],
        abc: [-1.2, 0, 0],
        xyz: [-1.2, 0, 0],
        label: `C2`,
        properties: {},
      },
      {
        species: [{ element: `O`, occu: 1, oxidation_state: 0 }],
        abc: [0, 0, 0],
        xyz: [0, 0, 0],
        label: `O1`,
        properties: {},
      },
      {
        species: [{ element: `N`, occu: 1, oxidation_state: 0 }],
        abc: [1.2, 0, 0],
        xyz: [1.2, 0, 0],
        label: `N1`,
        properties: {},
      },
      {
        species: [{ element: `C`, occu: 1, oxidation_state: 0 }],
        abc: [-1.2, 1.25, 0],
        xyz: [-1.2, 1.25, 0],
        label: `C3`,
        properties: {},
      },
    ],
    properties: {
      bonds: [
        { site_idx_1: 0, site_idx_2: 1, order: 1 },
        { site_idx_1: 1, site_idx_2: 2, order: 2 },
        { site_idx_1: 2, site_idx_2: 3, order: 3 },
        { site_idx_1: 1, site_idx_2: 4, order: `aromatic` },
      ],
    },
  }
</script>

<Structure
  structure={bond_order_playground}
  show_controls="always"
  scene_props={{
    camera_position: [0, 0, 12],
    show_site_labels: true,
    show_site_indices: true,
    bonding_options: { strength_threshold: 10 },
  }}
  style="height: 520px"
/>

Different Crystal Systems

Showcasing structures with different crystal systems.

svelte<script lang="ts">
  import { CRYSTAL_SYSTEMS, Structure } from 'matterviz'
  import { structures } from '$site/structures'
</script>

<ul class="crystal-systems">
  {#each structures.filter((struct) =>
      CRYSTAL_SYSTEMS.some((system) => struct.id.includes(system))
    ) as
    structure
    (structure.id)
  }
    {@const mp_id = structure.id.split(`-`).slice(0, 2).join(`-`)}
    {@const href = `https://materialsproject.org/materials/${mp_id}`}
    {@const crystal_system = structure.id.split(`-`).at(-1) || 'unknown'}
    <li>
      <h3><a {href}>{mp_id}</a> <small>{crystal_system}</small></h3>
      <Structure {structure} />
    </li>
  {/each}
</ul>

<style>
  ul.crystal-systems {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(500px, 1fr));
    gap: 1.5em;
    list-style: none;
    padding: 0;
    text-align: center;
    width: 95vw;
    margin: 2em calc(50cqw - 47.5vw);
  }
  ul.crystal-systems h3 {
    margin: 0.5em auto;
    font-size: 1.1em;
    display: flex;
    place-items: center;
    place-content: center;
  }
  ul.crystal-systems small {
    margin: 0 0 0 0.5em;
    font-weight: lighter;
    color: var(--text-color-muted);
  }
</style>

Load Structure from String

You can load structures directly from text content using the structure_string prop, supporting various formats (CIF, POSCAR, XYZ, JSON, etc.).

Structure: (parsed 0 atoms from 4.82kB)

No structure provided

svelte<script lang="ts">
  import { Structure } from 'matterviz'
  import { format_num } from '$lib'
  import c2ho_scientific_notation_xyz from '$site/molecules/C2HO-scientific-notation.xyz?raw'
  import c5_extra_data_xyz from '$site/molecules/C5-extra-data.xyz?raw'
  import cyclohexane from '$site/molecules/cyclohexane.xyz?raw'
  import aviary_CuF3K_triolith from '$site/structures/aviary-CuF3K-triolith.poscar?raw'
  import ba_ti_o3_tetragonal from '$site/structures/BaTiO3-tetragonal.poscar?raw'
  import mof_issue_127 from '$site/structures/mof-issue-127.cif?raw'
  import na_cl_cubic from '$site/structures/NaCl-cubic.poscar?raw'
  import ru_p_complex_cif from '$site/structures/P24Ru4H252C296S24N16.cif?raw'
  import pf_sd_1601634_cif from '$site/structures/PF-sd-1601634.cif?raw'
  import extended_xyz_quartz from '$site/structures/quartz.extxyz?raw'
  import scientific_notation_poscar from '$site/structures/scientific-notation.poscar?raw'
  import selective_dynamics from '$site/structures/selective-dynamics.poscar?raw'
  import tio2_cif from '$site/structures/TiO2.cif?raw'
  import vasp4_format from '$site/structures/vasp4-format.poscar?raw'

  const structure_files = [
    { name: `MOF (CIF)`, content: mof_issue_127 },
    { name: `Ru Complex (CIF)`, content: ru_p_complex_cif },
    { name: `PF Structure (CIF)`, content: pf_sd_1601634_cif },
    { name: `Cyclohexane (XYZ)`, content: cyclohexane },
    { name: `C2HO (XYZ)`, content: c2ho_scientific_notation_xyz },
    { name: `C5 (XYZ)`, content: c5_extra_data_xyz },
    { name: `CuF3K (POSCAR)`, content: aviary_CuF3K_triolith },
    { name: `BaTiO3 (POSCAR)`, content: ba_ti_o3_tetragonal },
    { name: `NaCl (POSCAR)`, content: na_cl_cubic },
    { name: `Quartz (ExtXYZ)`, content: extended_xyz_quartz },
    { name: `Scientific Notation (POSCAR)`, content: scientific_notation_poscar },
    { name: `Selective Dynamics (POSCAR)`, content: selective_dynamics },
    { name: `TiO2 (CIF)`, content: tio2_cif },
    { name: `VASP4 Format (POSCAR)`, content: vasp4_format },
  ]

  let selected_idx = $state(0)
  let parsed_structure = $state(undefined)
  let selected_file = $derived(structure_files[selected_idx])
</script>

<label style="display: block; margin-block: 1em">
  Structure:
  <select bind:value={selected_idx}>
    {#each structure_files as file, idx (file.name)}
      <option value={idx}>{file.name}</option>
    {/each}
  </select>
  &ensp;(parsed <strong>{parsed_structure?.sites?.length || 0}</strong> atoms from {
    format_num(selected_file.content.length)
  }B)
</label>

<Structure
  structure_string={selected_file.content}
  bind:structure={parsed_structure}
/>

Structure

Bi2Zr2O8-Fm3m.json

Explicit Bond Orders

Different Crystal Systems

mp-10018 cubic

mp-1183085 orthorhombic

mp-1183089 monoclinic

mp-1207297 tetragonal

mp-686119 triclinic

mp-862690 hexagonal

Po-simple cubic

Load Structure from String