Ketcher

Ketcher is an open-source web-based chemical structure editor incorporating high performance, good portability, light weight, and ability to easily integrate into a custom web-application. Ketcher is designed for chemists, laboratory scientists and technicians who draw structures and reactions.

Key Features

• ⚡️ Fast 2D structure representation that satisfies common chemical drawing standards
• :diamond_shape_with_a_dot_inside: 3D structure visualization
• :memo: Template library (including custom and user's templates)
• 🔩 Add atom and bond basic properties and query features, add aliases and Generic groups
• :cyclone: Stereochemistry support during editing, loading, and saving chemical structures
• :loop: Storing history of actions, with the ability to rollback to previous state
• :floppy_disk: Ability to load and save structures and reactions in MDL Molfile or RXN file format, InChI String, ChemAxon Extended SMILES, ChemAxon Extended CML file formats
• :microscope: Zoom in/out, hotkeys, cut/copy/paste
• :crystal_ball: OCR - ability to recognize structures at pictures (image files) and reproduce them
• :clipboard: Copy and paste between different chemical editors
• 🛠️ Settings support (Rendering, Displaying, Debugging)
• :camera: Use of SVG to achieve best quality in-browser chemical structure rendering

Editor builtin tools:

• Atom Tool, Bond Tool, and Template Tool to draw and edit structures
• Aromatize/De-aromatize Tool
• Calculate CIP Descriptors Tool
• Structure Check Tool
• MW and Structure Parameters Calculate Tool
• Select, modify, and erase connected and unconnected atoms and bonds using Selection Tool, or using Shift key
• Advanced Structure Clean up Tool (+ stereochemistry checking and structure layout)
• Simple Structure Clean up Tool (checks bonds length, angles and spatial arrangement of atoms)
• Easy to use R-Group and S-Group tools (Generic, Multiple group, SRU polymer, peratom, Data S-Group)
• Reaction Tool (reaction generating, manual and automatic atom-to-atom mapping)
• Flip/Rotate Tool

Installation and usage

At this moment Ketcher can be embedded into your application in two ways:

• as ready-to-run application (to find desired version please look at Assets block of releases). The application can be injected as IFrame or a separate page.
• as a react component library

Installation

npm install ketcher-core ketcher-react

Basic Setup

import { Editor } from 'ketcher-react';
import { StandaloneStructServiceProvider } from 'ketcher-standalone';

import 'ketcher-react/dist/index.css';

const structServiceProvider = new StandaloneStructServiceProvider();

function App() {
  return (
    <Editor
      staticResourcesUrl="/public"
      structServiceProvider={structServiceProvider}
      onInit={(ketcher) => {
        window.ketcher = ketcher;
      }}
    />
  );
}

FAQ

How to use react component library

Look at the following link for details.

Configure indigo service

You can find the instruction for service installation here.

Packages

Project	Status	Description
ketcher-core		Core functionality: domain, shared services, functions and interface declarations
ketcher-standalone		Contains only the functionality necessary to start Ketcher in standalone mode
ketcher-react		Package contains only the functionality necessary to define components.
ketcher-macromolecules		Package contains the macromolecules editor functionality and UI components

3D Viewer

Ketcher uses Miew-React for viewing and editing data in 3D.

You can find the latest version of Miew-React here. The last checked version - 1.0.0.

Macromolecules mode

Starting with version 3.0, Ketcher supports a new control in the top toolbar that allows switching to macromolecules editing mode. If you prefer having only small molecules editing mode available, you can remove the mode switcher from the toolbar by passing disableMacromoleculesEditor property to the Editor component.

import { Editor } from 'ketcher-react';

const App = () => {
  return (
    <Editor
      {/* ...rest of the properties */}
      disableMacromoleculesEditor
    />
  );
};

Please refer to the example/src/App.tsx file for a complete example of how to integrate Ketcher editor into your application.

Ketcher API

1. Structure Export Methods
2. Structure Import Methods
3. Editor Operations
4. View Control
5. Settings Management
6. Event System
7. React Component API
8. Macromolecules Mode
9. Service Providers
10. Supported Formats
11. Usage Examples
12. Internal Services (Advanced)
13. Error Handling

Structure Export Methods

All export methods return Promise<string> with the structure in the requested format.

getSmiles

getSmiles(isExtended?: boolean): Promise<string>

Returns SMILES (Simplified Molecular Input Line Entry System) representation.

Parameters: - isExtended (optional) - Use extended SMILES format (default: false)

Throws: Error in macromolecules mode

Example:

const smiles = await ketcher.getSmiles();
// Returns: "C1=CC=CC=C1"

const extended = await ketcher.getSmiles(true);
// Returns extended SMILES with stereochemistry

---

getExtendedSmiles

getExtendedSmiles(): Promise<string>

Alias for getSmiles(true).

---

getMolfile

getMolfile(molfileFormat?: 'v2000' | 'v3000'): Promise<string>

Returns MDL MOL file format.

Parameters: - molfileFormat (optional) - MOL file version: 'v2000', 'v3000', or auto-detect

Throws: Error if structure contains reaction arrows (use getRxn instead)

Example:

const mol = await ketcher.getMolfile('v3000');

---

getRxn

getRxn(molfileFormat?: 'v2000' | 'v3000'): Promise<string>

Returns RXN (Reaction) file format.

Parameters: - molfileFormat (optional) - RXN file version (default: 'v2000')

Throws: - Error if no reaction arrows present - Error in macromolecules mode

Example:

const rxn = await ketcher.getRxn('v3000');

---

getKet

getKet(): Promise<string>

Returns KET (Ketcher JSON) format - the native internal format.

Works in both micro and macromolecules modes.

Example:

const ket = await ketcher.getKet();
const ketObj = JSON.parse(ket);

---

getSmarts

getSmarts(): Promise<string>

Returns SMARTS (SMILES Arbitrary Target Specification) representation.

Throws: Error in macromolecules mode

---

getCml

getCml(): Promise<string>

Returns CML (Chemical Markup Language) format.

Throws: Error in macromolecules mode

---

getSdf

getSdf(molfileFormat?: 'v2000' | 'v3000'): Promise<string>

Returns SDF (Structure-Data File) format.

Parameters: - molfileFormat (optional) - Version (default: 'v2000')

Throws: Error in macromolecules mode

---

getRdf

getRdf(molfileFormat?: 'v2000' | 'v3000'): Promise<string>

Returns RDF (Reaction Data File) format.

Parameters: - molfileFormat (optional) - Version (default: 'v2000')

Throws: Error in macromolecules mode

---

getCDXml

getCDXml(): Promise<string>

Returns CDXML (ChemDraw XML) format.

Throws: Error in macromolecules mode

---

getCDX

getCDX(): Promise<string>

Returns CDX (ChemDraw binary) format as base64-encoded string.

Throws: Error in macromolecules mode

---

getInchi

getInchi(withAuxInfo?: boolean): Promise<string>

Returns InChI (IUPAC International Chemical Identifier) representation.

Parameters: - withAuxInfo (optional) - Include auxiliary information (default: false)

Example:

const inchi = await ketcher.getInchi();
// Returns: "InChI=1S/C6H6/c1-2-4-6-5-3-1/h1-6H"

---

getInChIKey

getInChIKey(): Promise<string>

Returns InChI Key (hashed InChI).

Example:

const key = await ketcher.getInChIKey();
// Returns: "UHOVQNZJYSORNB-UHFFFAOYSA-N"

---

getFasta

getFasta(): Promise<string>

Returns FASTA format for biological sequences.

Available in macromolecules mode.

---

getSequence

getSequence(format: '1-letter' | '3-letter'): Promise<string>

Returns sequence in 1-letter or 3-letter amino acid/nucleotide format.

Parameters: - format - Sequence format: '1-letter' or '3-letter'

Example:

const seq = await ketcher.getSequence('1-letter');
// Returns: "ACDEFG"

---

getIdt

getIdt(): Promise<string>

Returns IDT (Integrated DNA Technologies) format.

---

getAxoLabs

getAxoLabs(): Promise<string>

Returns AxoLabs format.

---

Structure Import Methods

setMolecule

setMolecule(structure: string, options?: SetMoleculeOptions): Promise<void>

Loads structure onto canvas, replacing existing structure.

Parameters: - structure - Structure string (format auto-detected) - options (optional) - Import options

SetMoleculeOptions:

interface SetMoleculeOptions {
  position?: { x: number; y: number };  // Top-left corner in Angstroms (Y increases upward)
  needZoom?: boolean;                   // Zoom to fit (default: true)
}

Automatically centers and zooms to fit structure.

Example:

// Load SMILES
await ketcher.setMolecule('C1=CC=CC=C1');

// Load at specific position
await ketcher.setMolecule('CCO', {
  position: { x: 5, y: 5 },
  needZoom: false
});

// Load MOL file
const molfile = `...`;
await ketcher.setMolecule(molfile);

// Load KET
const ket = JSON.stringify({ root: { nodes: [...] } });
await ketcher.setMolecule(ket);

---

addFragment

addFragment(structure: string, options?: SetMoleculeOptions): Promise<void>

Adds structure to canvas without removing existing content.

Parameters: Same as setMolecule

Example:

await ketcher.setMolecule('C1=CC=CC=C1');
await ketcher.addFragment('CCO', { position: { x: 10, y: 0 } });

---

setHelm

setHelm(helmStr: string): Promise<void>

Loads HELM (Hierarchical Editing Language for Macromolecules) notation structure.

Example:

await ketcher.setHelm('PEPTIDE1{A.G.F}$$$$V2.0');

---

Editor Operations

layout

layout(): Promise<void>

Performs automatic layout algorithm using Indigo service for smart positioning.

Throws: Error in macromolecules mode

Example:

await ketcher.layout();

---

circularLayoutMonomers

circularLayoutMonomers(): Promise<void>

Arranges monomers in circular layout.

Only available in macromolecules mode.

---

calculate

calculate(options?: CalculateData): Promise<CalculateResult>

Calculates molecular properties.

Returns:

interface CalculateResult {
  'molecular-weight': string;
  'most-abundant-mass': string;
  'monoisotopic-mass': string;
  'gross': string;                    // Molecular formula
  'mass-composition': string;
}

Throws: Error in macromolecules mode

Example:

const props = await ketcher.calculate();
console.log('Molecular weight:', props['molecular-weight']);
console.log('Formula:', props['gross']);

---

recognize

```typescript recognize(image: Blob, version?: s