Getting Started with QPeriodicTable — Features, Setup, and ExamplesQPeriodicTable is a lightweight, developer-friendly library designed to provide an interactive, customizable periodic table component for web and desktop applications. Whether you’re building an educational web app, a chemistry visualization tool, or an internal reference for a scientific product, QPeriodicTable aims to make element data accessible, attractive, and extensible.
What QPeriodicTable Provides
- Interactive element tiles: click or hover to reveal detailed element information (atomic number, symbol, name, atomic mass, electron configuration, oxidation states, and common isotopes).
- Customizable layouts: standard periodic table layout, long-form, compact, or grouped-by-property displays.
- Filtering & searching: instant filtering by name, symbol, atomic number, group, period, or custom properties (e.g., state at room temperature, metal/nonmetal).
- Themeable styling: color schemes for element categories (alkali metals, noble gases, transition metals, etc.) and easy CSS/stylesheet overrides.
- Data-driven: uses a JSON/CSV data source so you can extend element metadata or replace with localized names, alternative datasets, or experimental properties.
- Accessibility: keyboard navigation, ARIA roles, and screen-reader friendly markup where applicable.
- Event hooks & API: callbacks for element click/hover, programmatic selection, and methods to update or refresh the dataset.
- Export & print support: print-ready layouts and CSV/JSON export of selected elements or filters.
Use Cases
- Educational websites and online labs.
- Interactive textbooks and learning-management systems.
- Research tools that require element lookup and property comparison.
- Science museum kiosks and digital signage.
- Rapid prototyping for chemical software or app interfaces.
Installation & Setup
Below are typical installation paths depending on the environment (web, Electron, or desktop frameworks that accept web components).
Web (npm / yarn)
-
Install the package:
npm install qperiodictable # or yarn add qperiodictable -
Import in your JavaScript or TypeScript project:
import QPeriodicTable from 'qperiodictable'; import 'qperiodictable/dist/qperiodictable.css'; -
Add to your application:
<div id="periodic-root"></div> <script> const root = document.getElementById('periodic-root'); const table = new QPeriodicTable(root, { layout: 'standard', theme: 'light', dataUrl: '/data/elements.json' }); table.render(); </script>
CDN / Script Tag
<link rel="stylesheet" href="https://cdn.example.com/qperiodictable/qperiodictable.css"> <script src="https://cdn.example.com/qperiodictable/qperiodictable.min.js"></script> <div id="periodic-root"></div> <script> const table = new QPeriodicTable('#periodic-root', { theme: 'dark' }); table.render(); </script> Electron / Desktop
- Use the npm package in your renderer process as you would in a web app. Ensure CSS is loaded and consider packaging the element data locally for offline use.
Configuration Options (Common)
- layout: ‘standard’ | ‘long’ | ‘compact’
- theme: ‘light’ | ‘dark’ | custom theme object
- dataUrl: string (path or URL to JSON/CSV data)
- showIsotopes: boolean
- enableSearch: boolean
- categoriesColorMap: object — map category -> color hex
- onElementClick: function(elementData)
- onElementHover: function(elementData)
- keyboardNavigation: boolean
Example configuration:
const opts = { layout: 'standard', theme: { background: '#ffffff', text: '#222222', categories: { 'noble gas': '#9ad0f5', 'alkali metal': '#f9c0c0' } }, dataUrl: '/assets/elements.json', showIsotopes: false, enableSearch: true, onElementClick: (el) => console.log('clicked', el) }; Data Format
QPeriodicTable uses a simple, extensible JSON schema for elements. Example element entry:
{ "atomicNumber": 1, "symbol": "H", "name": "Hydrogen", "atomicMass": 1.008, "category": "nonmetal", "group": 1, "period": 1, "electronConfiguration": "1s1", "oxidationStates": [1, -1], "stateAtSTP": "gas", "isotopes": [ { "massNumber": 1, "abundance": 0.99985 }, { "massNumber": 2, "abundance": 0.00015 } ] } You can add fields like meltingPoint, boilingPoint, discoveryYear, or localizedName — the component will surface fields that you configure it to show.
Examples
Basic render with search and click handler
import QPeriodicTable from 'qperiodictable'; const table = new QPeriodicTable('#root', { enableSearch: true, onElementClick: (el) => alert(`${el.name} — ${el.symbol} (${el.atomicNumber})`) }); table.render(); Custom color scheme and filtered view
const table = new QPeriodicTable('#root', { theme: { categories: { 'metalloid': '#b5e7a0', 'noble gas': '#d0e7ff' } }, dataUrl: '/data/elements.json', }); table.filterByCategory(['metalloid', 'noble gas']); Programmatic selection & exporting
table.selectElement(26); // highlight Iron (Fe) const csv = table.exportSelected('csv'); console.log(csv); Accessibility & Internationalization
- Keyboard-first navigation: arrow keys move focus, Enter opens details.
- ARIA roles and labels are provided for element tiles and search controls.
- Data can include localized names and descriptions; the UI can switch locale via configuration (e.g., locale: ‘en’ | ‘ru’ | ‘fr’).
Performance Tips
- Lazy-load heavy datasets or isotope lists on demand.
- Virtualize the grid for very compact or large custom layouts.
- Cache element data locally (IndexedDB or localStorage) for offline-first apps.
Troubleshooting
- Missing styles: ensure the CSS file is imported or the CDN stylesheet link is present.
- No data shown: confirm dataUrl path or provide inline data via the data option.
- Accessibility issues: enable keyboardNavigation and test with a screen reader; update ARIA labels via options if needed.
Example Project Structure
- /src
- index.html
- app.js
- styles.css
- /data
- elements.json
- package.json
Extending QPeriodicTable
- Add new data fields and update templates for element detail panes.
- Build plugins for plotting properties (e.g., atomic radius heatmaps).
- Integrate with chemistry toolkits (Open Babel, RDKit) via backend services for deeper calculations.
Summary
QPeriodicTable is designed to be flexible, accessible, and easy to integrate. Start by installing the package, load or provide a JSON dataset, choose a layout and theme, and wire up event handlers for interactivity. From there you can extend data, create custom views, and integrate it into education or research workflows.
Leave a Reply