Components
Term
A clinical word shown with its everyday meaning attached, so you can read a sentence without having to look anything up.
Usage
pnpm dlx shadcn@latest add @opsinjs/term
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { Term, TermGlossaryProvider } from "@/components/ui/term"<TermGlossaryProvider glossary={GLOSSARY}>
<p>
An <Term id="acute" /> problem started suddenly.
</p>
</TermGlossaryProvider>Examples
term · base base · style base-lyraOpen under the product themeReading a paragraph without leaving it
Two terms is near the ceiling for one paragraph. A third carries once, so the word stays
marked and reachable but its definition is not reprinted.
term-in-a-sentence · base base · style base-lyraOpen under the product themeimport {
Term,
TermGlossaryProvider,
type GlossaryEntry,
} from "@/components/ui/term"
/* Hoisted to a module constant rather than written inline in the JSX below.
The provider rebuilds its lookup whenever the array's identity changes, and
an array literal in a render is a new identity every time. */
const GLOSSARY: readonly GlossaryEntry[] = [
{
id: "acute",
word: "acute",
plain: "sudden, or short-lasting",
showBoth: "first-use",
},
{
id: "egfr",
word: "eGFR",
expansion: "estimated glomerular filtration rate",
plain: "an estimate of how well your kidneys are filtering",
speech: "e G F R",
showBoth: "always",
},
]
export default function TermInASentence() {
return (
<TermGlossaryProvider glossary={GLOSSARY}>
<div className="flex w-full max-w-(--opsin-measure-comfortable,66ch) flex-col gap-opsin-4 text-opsin-body">
<p className="m-0">
Your letter uses the word <Term id="acute" />, which describes how
quickly something started rather than how serious it is.
</p>
<p className="m-0">
It also reports an <Term id="egfr" />. That number comes from a blood
test and from details the laboratory already holds about you.
</p>
<p className="m-0">
A second <Term id="egfr" once /> on the same page is marked, and its
definition is still there for anyone reading with speech. It is not
repeated in front of everybody else.
</p>
</div>
</TermGlossaryProvider>
)
}An abbreviation needs two things
The expansion says what the letters stand for, the definition what the thing is. Both
entries are marked showBoth: "always", so both arrive inline, and SpO2 adds speech.
term-an-abbreviation · base base · style base-lyraOpen under the product themeimport {
Term,
TermGlossaryProvider,
type GlossaryEntry,
} from "@/components/ui/term"
const GLOSSARY: readonly GlossaryEntry[] = [
{
id: "spo2",
word: "SpO2",
expansion: "oxygen saturation",
plain: "an estimate of how much oxygen your blood is carrying",
speech: "S P O 2",
showBoth: "always",
},
{
id: "benign",
word: "benign",
plain: "not cancer",
showBoth: "always",
},
]
export default function TermAnAbbreviation() {
return (
<TermGlossaryProvider glossary={GLOSSARY}>
<div className="flex w-full max-w-(--opsin-measure-comfortable,66ch) flex-col gap-opsin-4 text-opsin-body">
<p className="m-0">
A wrist device reports <Term id="spo2" />, and it is an estimate rather
than a measurement. Movement, cold hands and skin tone all affect it.
</p>
<p className="m-0">
A report describing a finding as <Term id="benign" /> is using a word
that appears on paperwork and nowhere else in everyday speech.
</p>
</div>
</TermGlossaryProvider>
)
}When to use it
Use it when
- A clinical word the reader will meet on a letter, in a consultation, or on a test result, so a plainer word cannot replace it.
- An abbreviation whose expansion the reader needs at least once: HbA1c, eGFR, BP, SpO2.
- A word whose everyday meaning differs from its clinical one, such as 'chronic' or 'acute'.
Do not use it when
- The explanation runs past a sentence or two, or carries a caveat as well as a definition.Use
calloutinstead. - The point is a standing statement about what this product is and is not.Use
disclaimer-noteinstead. - You need general help text for a non-clinical interface control.Use
tooltipinstead. - The reader needs to browse or search every definition rather than read one in place.Use
tableinstead. - What needs explaining is a number, a unit or a precision rather than a word.Use
valueinstead.
Clinical meaning
Asserts. That this word has this everyday meaning in the product's glossary. That translation is the product's claim, not a clinician's, and opsinjs ships an empty glossary. See Health.
Never read as. A statement about the reader's condition, or advice. Chronic means long-lasting is a translation; chronic means you will have this for life is a prognosis the glossary is not for.
Colour axis. Neither. The mark is a dotted underline that survives greyscale. See Health.
Thresholds. None. Term puts no reading on the screen, so it holds no threshold and stamps no value.
Gap you must build around. A call site naming a plain-only entry gets the authored
sentence and a development warning, because a runtime cannot rewrite one. No lint rule
catches it.
Accessibility
The disclosure is a real button named by its visible word, meeting SC 2.5.3 Label in
Name. present has no hover value, so the definition never depends on hover, and
collapsed it is display: none yet still reaches the reader as the trigger's
description. The mark changes form, not colour: dotted at rest, solid while open. The
audit made the trigger's focus ring honour --opsin-border-focus and
--opsin-border-focus-offset in place of a hardcoded 2px width and offset, so the
indicator grows with a reader's focus width.
Residual items.
- The inline trigger falls under the 44 by 44 floor and relies on the SC 2.5.8 inline exception, and adjacent wrapped triggers can overlap.
aria-controlsdeliberately points at the closeddisplay: nonepanel. No assistive technology has been tested against it, so the lived experience is unverified.
| Key | Action | Notes |
|---|---|---|
| Tab | Move focus to the disclosure control | One tab stop per term. The inline presentation has none. |
| Shift+Tab | Move focus backwards to it | Reverse order matches where the word sits in the sentence. |
| Enter | Show or hide the definition | Native activation. The definition appears beside the word, not over it. |
| Space | Show or hide the definition | Native activation, which is what stops the page scrolling. |
| Escape | Hide the definition | Consumed only while open, so the sheet around it survives. |
Contrast: 36 measured token pairs, 15 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from TermProps in registry/bases/base/term.tsx.
Prop
Type
Generated from TermGlossaryProviderProps in registry/bases/base/term.tsx.
There is no way to supply a definition at a call site. Definitions live in the glossary
and arrive once through TermGlossaryProvider, so they stay consistent and reviewable.
An id the glossary does not hold renders unmarked and warns in development, printing
children where a call site supplied any and otherwise the raw id.