`<bmx-chem-editor>`

A chemical structure editor for electronic lab notebooks, compound registration and LIMS: draw a molecule with the mouse, a pen or the keyboard; read and write molfiles (V2000 and V3000), SD files and SMILES; see its formula, average and monoisotopic mass as you draw.

33 properties · 4 events · 21 methods · 10 parts

Example

Try it with your own molfiles and SD files in confidence: they are opened by your browser, on your device. Nothing is uploaded, no copy reaches us or anyone else, and nothing is kept once you close this tab.

Reading...

Show markup

<bmx-chem-editor id="ex-chem" label="Compound" name="structure" description="Draw with the tools, type on an atom (N, OH, CO2Me), or paste a SMILES or molfile. Step through the records, search them for a substructure in the Search view, show R/S and E/Z from the More menu, and save a molfile, SD file or picture."></bmx-chem-editor>
<p class="note" id="ex-chem-out" role="status" style="margin: 12px 0 0; overflow-wrap: anywhere">Reading...</p>

<bmx-chem-editor id="ex-chem-rxn" label="Reaction" stereo-labels style="margin-block-start: 24px" description="A reaction: reactants before the arrow, products after it, the catalyst over it. Draw arrows with the arrow tool; open and save RXN files and reaction SMILES."></bmx-chem-editor>

<script type="module">
  await customElements.whenDefined('bmx-chem-editor');
  const editor = document.getElementById('ex-chem');
  const out = document.getElementById('ex-chem-out');

  // A small compound list as SMILES, one per line with its name: the editor opens it as records to step through and search.
  editor.molecule = [
    'CC(=O)Oc1ccccc1C(=O)O Aspirin',
    'C[C@H](Cc1ccc(cc1)CC(C)C)C(=O)O Ibuprofen (R)',
    'Cn1cnc2c1c(=O)n(C)c(=O)n2C Caffeine',
    'CC(C)[C@@H]1CC[C@@H](C)C[C@H]1O Menthol',
    'OC[C@H]1O[C@@H](O)[C@H](O)[C@@H](O)[C@@H]1O Glucose',
    'CC/C(=C(\\c1ccccc1)c1ccc(OCCN(C)C)cc1)c1ccccc1 Tamoxifen',
    'CC(=O)Nc1ccc(O)cc1 Paracetamol',
    'CN1CCC[C@H]1c1cccnc1 Nicotine',
    'CC1([C@@H](N2[C@H](S1)[C@@H](C2=O)NC(=O)Cc1ccccc1)C(=O)O)C Penicillin G',
    'CN1C(=O)CN=C(c2ccccc2)c2cc(Cl)ccc21 Diazepam',
  ].join('\n');

  const report = async () => {
    const info = await editor.getInfo();
    out.textContent = info.atoms
      ? `${info.formula}, ${info.weight.toFixed(2)} g/mol, ${info.stereocentres} stereocentres. Canonical SMILES: ${await editor.getSmiles({ canonical: true })}`
      : 'Draw a structure to see its formula and SMILES.';
  };
  editor.addEventListener('bmxChange', report);
  await report();

  // An amino acid made into its methyl ester, written as a reaction SMILES: reactants > catalyst > products.
  document.getElementById('ex-chem-rxn').molecule = 'C[C@H](N)C(=O)O.CO>[H+]>C[C@H](N)C(=O)OC.O';
</script>

<bmx-chem-editor label="Compound" name="structure" molecule="CC(=O)Oc1ccccc1C(=O)O"></bmx-chem-editor>

Tools draw atoms (any element, from the periodic table), bonds (single, double, triple, wedge, hash, wavy, crossed), zig-zag chains, rings from three to eight and benzene (on their own, hung from an atom, or fused on a bond), charges, functional-group abbreviations (Me, OMe, CO2Et, Boc, Ts and more, kept as superatoms) and templates. New atoms that land on old ones join them, so rings fuse and chains close (Shift-click a ring onto an atom for a spiro ring; drag from an atom to aim a bond, chain or ring). Typing on an atom changes it (double-click it, or press Enter on it: NH2, O-, 13C, OMe). Clean lays the structure out again; wedges, hashes and double-bond geometry are kept as stereochemistry, written to SMILES as @/@@ and //\. An SD file opens as records to step through, with their data items.

Reactions: the arrow tool draws a reaction arrow; the pieces before it are the reactants, after it the products, along it the agents. RXN files (V2000 and V3000) and reaction SMILES (CC(=O)O.OCC>>CC(=O)OCC.O) open as reactions and save as them. getSmiles({ canonical: true }) gives one SMILES per structure, whatever its drawing; R/S and E/Z labels can be shown beside stereocentres and double bonds (Cahn-Ingold-Prelog rules 1 and 2). The Search view finds a substructure (SMARTS, SMILES, or the drawing or its selection) in every record of an SD file and shows the matches.

The drawing is fully usable from the keyboard: arrows move between atoms and bonds, letters change elements, digits add bonds, and every change is announced. The Atoms and bonds view lists and edits everything as tables; the Text view edits the SMILES or molfile directly. Nothing leaves the page. In a form, name receives the molfile (or SMILES, SD file or JSON, by value-format).

Properties

Property	Attribute	Type	Default	Description
`abbreviations`	`abbreviations`	`BmxChemAbbreviation[] \| string`	—	More abbreviations for the group tool and for typed labels, as `[{ label, smiles, name }]` or JSON (the first atom bonds to the rest).
`atomNumbers`	`atom-numbers`	`boolean`	`false`	Show atom numbers.
`bondLength`	`bond-length`	`number`	`34`	A bond's length on screen at 100%, in CSS pixels.
`bondType`	`bond-type`	`BmxChemEditorBond`	`'single'`	The bond the bond tool draws. Two-way.
`carbons`	`carbons`	`'none' \| 'terminal' \| 'all'`	`'none'`	Which carbons are labelled: `none` (only where needed), `terminal` or `all`.
`description`	`description`	`string`	—	Help text below the editor.
`disabled`	`disabled`	`boolean`	`false`	Disable the editor.
`elementNames`	`element-names`	`Record<string, string> \| string`	—	Element names for descriptions read aloud, by symbol, as an object or JSON (`{ "N": "Stickstoff" }`).
`elementSymbol`	`element-symbol`	`string`	`'C'`	The element the atom tool draws, by symbol (`N`, `Cl`). Two-way.
`errorText`	`error-text`	`string`	—	An error supplied by the page.
`group`	`group`	`string`	`'Me'`	The abbreviation the group tool puts on (`OMe`, `CO2Et`, ...). Two-way.
`hideInfo`	`hide-info`	`boolean`	`false`	Hide the formula and masses under the drawing.
`hideLabel`	`hide-label`	`boolean`	`false`	Hide the label visually while keeping it as the accessible name.
`hideToolbar`	`hide-toolbar`	`boolean`	`false`	Hide the toolbar (for showing a structure).
`label`	`label`	`string`	—	The field's label: names the whole control.
`messages`	`messages`	`Record<string, string> \| string`	—	Problem messages in place of the English ones, by code (`valence`, `smiles-syntax`, ...), as an object or JSON.
`molecule`	`molecule`	`BmxChemMolecule \| string \| null`	`null`	The structure: a molecule object, or text - a SMILES, a molfile, an SD file, an RXN file or a reaction SMILES. Two-way: `bmxChange` reports every edit.
`monochrome`	`monochrome`	`boolean`	`false`	Draw every atom in the text colour instead of by element.
`name`	`name`	`string`	—	The field's name in a form.
`panel`	`panel`	`boolean`	`true`	Show the details panel. Two-way.
`readonly`	`readonly`	`boolean`	`false`	Allow looking, selecting, copying and saving, but not changing.
`requireValid`	`require-valid`	`boolean`	`false`	Keep the form from submitting while any problem is an error.
`required`	`required`	`boolean`	`false`	Keep the form from submitting while the drawing is empty.
`ring`	`ring`	`BmxChemEditorRing`	`'benzene'`	The ring the ring tool draws. Two-way.
`src`	`src`	`string`	—	An address to read the structure from (the page's own server): a molfile, SD file, RXN file or SMILES.
`stereoLabels`	`stereo-labels`	`boolean`	`false`	Show R/S beside stereocentres and E/Z beside double bonds (Cahn-Ingold-Prelog rules 1 and 2). Two-way.
`strings`	`strings`	`Partial<BmxChemEditorStrings> \| string`	—	Words to show instead of the English ones, as an object or JSON.
`template`	`template`	`string`	`'Naphthalene'`	The template the template tool puts on, by name. Two-way.
`templates`	`templates`	`BmxChemTemplate[] \| string`	—	The templates offered, as `[{ name, smiles }]` or JSON. Default: common rings and scaffolds.
`textFormat`	`text-format`	`'smiles' \| 'molfile' \| 'molfile-v3000'`	`'smiles'`	The text view's format. Two-way.
`tool`	`tool`	`BmxChemEditorTool`	`'bond'`	The tool in use. Two-way.
`valueFormat`	`value-format`	`BmxChemEditorValueFormat`	`'molfile'`	What the form receives under `name`: `molfile` (default), `molfile-v3000`, `smiles`, `canonical-smiles`, `sdf` (every record) or `json`. A reaction gives an RXN file or a reaction SMILES.
`view`	`view`	`BmxChemEditorView`	`'draw'`	The view shown. Two-way.

Events

Event	Detail	Description
`bmxChange`	`BmxChemChangeDetail`	Fired after the structure changes.
`bmxEdit`	`BmxChemEditDetail`	Fired before an edit. Cancel it to refuse the edit.
`bmxSelect`	`BmxChemSelectDetail`	Fired when the selection or the focused atom or bond changes.
`bmxValidate`	`BmxChemValidateDetail`	Fired after each check.

Methods

Method	Signature	Description
`clean`	`clean() => Promise<void>`	Lay the structure out again, keeping its stereochemistry.
`export`	`export(kind: BmxChemExportKind) => Promise<Blob>`	A file of the structure: a molfile, SD file, SMILES, SVG or PNG picture, or JSON.
`getInfo`	`getInfo() => Promise<BmxChemInfo>`	Formula, masses, counts and SMILES.
`getMolecule`	`getMolecule() => Promise<BmxChemMolecule>`	The structure now (a copy).
`getMolfile`	`getMolfile(version?: "V2000" \| "V3000") => Promise<string>`	The molfile of the structure.
`getProblems`	`getProblems() => Promise<BmxChemProblem[]>`	The problems found by the last check.
`getReaction`	`getReaction() => Promise<BmxChemReaction \| null>`	The drawing as a reaction - its reactants, agents and products - or null when it has no reaction arrow.
`getRecords`	`getRecords() => Promise<{ molecule: BmxChemMolecule; data: Record<string, string>; }[]>`	Every record of an SD file (just the one structure otherwise), with its data items.
`getSelection`	`getSelection() => Promise<BmxChemSelectDetail>`	The selection and the focused atom or bond.
`getSmiles`	`getSmiles(options?: BmxChemSmilesOptions) => Promise<string>`	The SMILES of the structure (stereochemistry from the drawing); with `canonical`, the same text for the same structure however drawn. A reaction gives a reaction SMILES.
`getStereoLabels`	`getStereoLabels() => Promise<{ atoms: Record<number, "R" \| "S">; bonds: Record<number, "E" \| "Z">; }>`	The R/S and E/Z descriptors (Cahn-Ingold-Prelog rules 1 and 2), by atom id and bond id.
`goToRecord`	`goToRecord(index: number) => Promise<void>`	Show record `index` (from 0) of an SD file.
`load`	`load(file: Blob \| string, fileName?: string) => Promise<BmxChemProblem[]>`	Read a file (molfile, SD file or SMILES) as an edit that can be undone. Returns what reading found.
`redo`	`redo() => Promise<boolean>`
`save`	`save(kind?: BmxChemExportKind, fileName?: string) => Promise<void>`	Download a file of the structure (see `export`).
`search`	`search(query: string) => Promise<BmxChemSearchResult[]>`	Find a substructure - SMARTS or SMILES - in every record (or the one structure), and show the results in the Search view. Resolves with the records that match; rejects when the query cannot be read.
`select`	`select(atoms?: number[], bonds?: number[], arrows?: number[]) => Promise<void>`	Select atoms and bonds (by id) and reaction arrows (by index).
`setFocus`	`setFocus() => Promise<void>`
`setMolecule`	`setMolecule(molecule: BmxChemMolecule \| string, options?: { keepHistory?: boolean; }) => Promise<void>`	Replace the structure (an object, a SMILES, a molfile or an SD file). With `keepHistory`, it can be undone.
`undo`	`undo() => Promise<boolean>`
`validate`	`validate() => Promise<BmxChemProblem[]>`	Check now. Returns every problem.

Slots

Slot	Description
`description`	Rich help text, in place of the `description` property.
`label`	Rich label content, in place of the `label` property.

CSS shadow parts

Part	Description
`canvas`	The drawing area.
`description`	The help text under the field.
`details`	The details panel.
`info`	The formula and masses under the drawing.
`label`	The label element.
`menu`	The menus and the periodic table.
`search`	The search view.
`table`	The atoms and bonds tables.
`text`	The text view.
`toolbar`	The bars of tools, views and commands.

CSS custom properties

Property	Description
`--bmx-chem-editor-background`	The drawing's background.
`--bmx-chem-editor-bond-color`	Bonds and carbon labels.
`--bmx-chem-editor-bromine`	Bromine labels.
`--bmx-chem-editor-details-width`	The width of the details panel.
`--bmx-chem-editor-halogen`	Fluorine and chlorine labels.
`--bmx-chem-editor-height`	The height of the drawing.
`--bmx-chem-editor-iodine`	Iodine labels.
`--bmx-chem-editor-label-font-size`	The label's font size.
`--bmx-chem-editor-match`	Search matches in the result pictures.
`--bmx-chem-editor-metal`	Metal labels.
`--bmx-chem-editor-nitrogen`	Nitrogen labels.
`--bmx-chem-editor-other`	Other elements' labels.
`--bmx-chem-editor-oxygen`	Oxygen labels.
`--bmx-chem-editor-phosphorus`	Phosphorus labels.
`--bmx-chem-editor-radius`	Corner radius of the frame.
`--bmx-chem-editor-selected`	The selection's highlight.
`--bmx-chem-editor-sulfur`	Sulfur labels.
`--bmx-chem-editor-support-font-size`	Font size of the description and error message.