kekule-svelte

Svelte 5 wrapper for Kekule.js - render and edit organic compound structures from SMILES strings.

Overview

kekule-svelte provides Svelte 5 components for rendering and editing chemical molecular structures. It wraps Kekule.js, a powerful JavaScript library for chemoinformatics, and offers:

• Read-only 2D molecular structure viewers
• 3D molecular structure viewers with WebGL
• Full interactive structure editors
• Reaction diagram rendering
• SMILES validation and conversion utilities
• Molecular property calculations
• Export to SVG and PNG formats

Installation

bun add kekule-svelte
# or
npm install kekule-svelte

Quick Start

<script lang="ts">
  import { KekuleViewer } from 'kekule-svelte';
</script>

<!-- Render Aspirin -->
<KekuleViewer smiles="CC(=O)Oc1ccccc1C(=O)O" height="360px" />

Components

KekuleViewer

A read-only 2D structure viewer. Renders molecular structures from SMILES strings with optional toolbar and mouse interaction.

<KekuleViewer
  smiles="CCO"
  width="100%"
  height="360px"
  showToolbar={false}
  interactive={false}
  background="transparent"
  onReady={(viewer) => console.log('Ready:', viewer)}
  onError={(error) => console.error('Error:', error)}
/>

Props

Exported Methods

Use bind:this to access these methods:

<script lang="ts">
  import { KekuleViewer } from 'kekule-svelte';
  let ref = $state<any>();
</script>

<KekuleViewer smiles="CCO" bind:this={ref} />

<button onclick={() => ref?.downloadSVG('ethanol.svg')}>Download SVG</button>

KekuleEditor

A full interactive structure drawing editor powered by Kekule.js Composer. Emits SMILES on every structural change.

<script lang="ts">
  import { KekuleEditor } from 'kekule-svelte';
  let smiles = $state('');
</script>

<KekuleEditor
  smiles="c1ccccc1"
  height="480px"
  onSmiles={(s) => (smiles = s)}
  onReady={(editor) => console.log('Editor ready:', editor)}
/>

Props

Exported Methods

KekuleReaction

Renders a 2D reaction diagram from a reaction SMILES string.

<KekuleReaction
  reaction="CCO.CC(=O)O>>CC(=O)OCC.O"
  height="220px"
  onReady={(viewer) => console.log('Ready:', viewer)}
  onError={(error) => console.error('Error:', error)}
/>

Reaction SMILES format: reactant1.reactant2>>product1.product2 (multiple reactants or products separated by dots).

Props

Kekule3DViewer

A 3D molecular structure viewer using Kekule.js WebGL renderer. Renders molecules in 3D space with rotation and zoom controls.

<Kekule3DViewer
  smiles="CCO"
  height="400px"
  renderMode="ballAndStick"
  showToolbar={true}
  onReady={(viewer) => console.log('3D Ready:', viewer)}
  onError={(error) => console.error('Error:', error)}
/>

Props

Exported Methods

Utilities

Loader Functions

import { loadKekule, isKekuleReady } from 'kekule-svelte';

// Load Kekule.js from CDN (singleton - safe to call multiple times)
const K = await loadKekule();

// Check if already loaded
if (isKekuleReady()) {
  // Kekule.js is available
}

Kekule.js is loaded once from jsDelivr CDN when the first component mounts. Subsequent calls return the same Promise.

Property Calculations

import { getMoleculeProperties, computeLipinski, formatFormula, loadKekule } from 'kekule-svelte';

// Get molecular properties from SMILES
const K = await loadKekule();
const props = getMoleculeProperties('CCO', K);
// Returns: { formula: 'C2H6O', molecularWeight: 46.07, atomCount: 9, ... }

// Check Lipinski's Rule of Five
const lipinski = computeLipinski({ mw: 180.16, logp: 1.19, hbd: 1, hba: 4 });
// Returns: { pass: true, rules: [...] }

// Format formula with subscript characters
formatFormula('C9H8O4'); // Returns 'C\u2089H\u2088O\u2084'

Available Functions

SvelteKit SSR Support

For SvelteKit applications with server-side rendering, use the SSR-safe entry point:

// In a +page.svelte or +layout.svelte
<script lang="ts">
  import { onMount } from 'svelte';
  let KekuleViewer: any;

  onMount(async () => {
    // Dynamic import ensures client-side only
    const mod = await import('kekule-svelte/index-ssr');
    KekuleViewer = mod.KekuleViewer;
  });
</script>

{#if KekuleViewer}
  <svelte:component this={KekuleViewer} smiles="CCO" />
{/if}

Custom Loading and Error States

Use Svelte 5 snippets to customize loading and error displays:

<KekuleViewer smiles="CCO">
  {#snippet loading()}
    <div class="my-spinner">Loading molecule...</div>
  {/snippet}
  {#snippet error({ error })}
    <div class="my-error">Failed to render: {error}</div>
  {/snippet}
</KekuleViewer>

How It Works

kekule-svelte loads Kekule.js from jsDelivr CDN the first time a component mounts. The loader is a singleton - it returns the same Promise regardless of how many components call it:

const K1 = await loadKekule();
const K2 = await loadKekule();
console.log(K1 === K2); // true

Svelte 5 Patterns

This library uses modern Svelte 5 patterns:

Requirements

• Svelte 5.0.0 or higher
• Browser environment (Kekule.js requires DOM)

Documentation

Full documentation available at kekule-svelte.makeez.dev

License

MIT - Makeez Labs