🦷 react-odontogram

A modern, interactive React Odontogram component for dental chart visualization and data collection. Built with SVG and React hooks — fully customizable, accessible, and designed for clinical or academic applications.

🖼️ Preview

| Light Mode | Dark Mode | | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | | | |

🧩 Demo

👉 Live Preview: https://biomathcode.github.io/react-odontogram

📦 Installation

# Using npm
npm install react-odontogram

# Using pnpm
pnpm add react-odontogram

# Using yarn
yarn add react-odontogram

Make sure you have react and react-dom installed as peer dependencies.

🚀 Quick Start

import { Odontogram } from "react-odontogram";
import "react-odontogram/style.css";

export default function App() {
  const handleChange = (selectedTeeth) => {
    console.log(selectedTeeth);
    /*
      Example output:
      [
        {
          "id": "teeth-21",
          "notations": {
            "fdi": "21",
            "universal": "9",
            "palmer": "1UL"
          },
          "type": "Central Incisor"
        },
        {
          "id": "teeth-12",
          "notations": {
            "fdi": "12",
            "universal": "7",
            "palmer": "2UR"
          },
          "type": "Lateral Incisor"
        }
      ]
    */
  };

  return <Odontogram onChange={handleChange} />;
}

🧠 onChange Return Type

The onChange callback returns an array of selected teeth objects:

type ToothDetail = {
  id: string;
  notations: {
    fdi: string;
    universal: string;
    palmer: string;
  };
  type: string;
};

Example JSON output:

[
  {
    "id": "teeth-21",
    "notations": {
      "fdi": "21",
      "universal": "9",
      "palmer": "1UL"
    },
    "type": "Central Incisor"
  },
  {
    "id": "teeth-12",
    "notations": {
      "fdi": "12",
      "universal": "7",
      "palmer": "2UR"
    },
    "type": "Lateral Incisor"
  }
]

⚙️ Props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | defaultSelected | string[] | [] | Tooth IDs selected on first render. | | singleSelect | boolean | false | Allow selecting only one tooth at a time (clicking the selected tooth clears it). | | onChange | (selectedTeeth: ToothDetail[]) => void | — | Called whenever selection changes. | | name | string | "teeth" | Name used for hidden form input. | | className | string | "" | Additional class for wrapper customization. | | theme | "light" \| "dark" | "light" | Applies built-in light/dark palette. | | colors | { darkBlue?: string; baseBlue?: string; lightBlue?: string } | {} | Override palette colors. | | notation | "FDI" \| "Universal" \| "Palmer" | "FDI" | Display notation in native tooth titles/tooltips. | | tooltip | { placement?: Placement; margin?: number; content?: ReactNode \| ((payload?: ToothDetail) => ReactNode) } | { placement: "top", margin: 10 } | Tooltip behavior and custom content renderer. | | showTooltip | boolean | true | Enables/disables tooltip rendering. | | showHalf | "full" \| "upper" \| "lower" | "full" | Render full chart or only upper/lower arches. | | maxTeeth | number | 8 | Number of teeth per quadrant (for baby/mixed dentition views). | | teethConditions | ToothConditionGroup[] | undefined | Colorize specific teeth by condition. | | readOnly | boolean | false | Disable interactions and selection changes. | | showLabels | boolean | false | Show the condition legend under the chart. | | layout | "circle" \| "square" | "circle" | Render classic arch layout or square/row layout. | | styles | React.CSSProperties | undefined | Inline styles applied to the root container. |

Placement values:

type Placement =
  | "top"
  | "top-start"
  | "top-end"
  | "right"
  | "right-start"
  | "right-end"
  | "bottom"
  | "bottom-start"
  | "bottom-end"
  | "left"
  | "left-start"
  | "left-end";

teethConditions shape:

type ToothConditionGroup = {
  label: string;
  teeth: string[]; // e.g. ["teeth-11", "teeth-12"]
  outlineColor: string;
  fillColor: string;
};

🧩 Common Recipes

1) Render a custom tooltip

import { Odontogram } from "react-odontogram";
import "react-odontogram/style.css";

export default function CustomTooltipExample() {
  return (
    <Odontogram
      tooltip={{
        placement: "top",
        content: (payload) => (
          <div style={{ minWidth: 140 }}>
            <strong>Tooth {payload?.notations.fdi}</strong>
            <div>{payload?.type}</div>
            <small>Universal: {payload?.notations.universal}</small>
          </div>
        ),
      }}
    />
  );
}

2) Change theme and colors

import { Odontogram } from "react-odontogram";
import "react-odontogram/style.css";

export default function ThemeExample() {
  return (
    <Odontogram
      className="my-odontogram"
      theme="dark"
      colors={{
        darkBlue: "#7c9cff",
        baseBlue: "#c7d2fe",
        lightBlue: "#4f46e5",
      }}
    />
  );
}

.my-odontogram {
  --odontogram-tooltip-bg: #0f172a;
  --odontogram-tooltip-fg: #f8fafc;
}

3) Show teethConditions (with legend)

import { Odontogram } from "react-odontogram";
import "react-odontogram/style.css";

const conditions = [
  {
    label: "caries",
    teeth: ["teeth-16", "teeth-26", "teeth-36"],
    fillColor: "#ef4444",
    outlineColor: "#b91c1c",
  },
  {
    label: "filling",
    teeth: ["teeth-14", "teeth-24"],
    fillColor: "#60a5fa",
    outlineColor: "#1d4ed8",
  },
];

export default function ConditionsExample() {
  return <Odontogram teethConditions={conditions} showLabels readOnly />;
}

4) Adjust tooltip position

import { Odontogram } from "react-odontogram";
import "react-odontogram/style.css";

export default function TooltipPositionExample() {
  return (
    <Odontogram
      tooltip={{
        placement: "right-start", // try: top, right, bottom-end, left-start...
        margin: 18, // larger = farther from tooth, smaller = closer
      }}
    />
  );
}

🦷 Tooth Data Model

Each tooth is internally defined in a structured format:

{
  name: "1",
  type: "Central Incisor",
  outlinePath: "...",
  shadowPath: "...",
  lineHighlightPath: "..."
}

This makes it easy to extend or customize if you fork the library.

🧪 Development

Run locally:

git clone https://github.com/biomathcode/react-odontogram.git
cd react-odontogram
pnpm install
pnpm dev

To preview Storybook:

pnpm storybook

🪶 License

MIT © biomathcode

💬 Feedback

If this library helps your dental project, please ⭐ the repo or open issues/PRs for enhancements!