PsychRatingScales
<co-psych-rating-scales>PsychRatingScales gives PHQ-9, GAD-7 and the C-SSRS screen in tabs, scores them live with the published bands, and escalates suicide risk with the actions to take.
import { PsychRatingScales } from 'health-components';
Examples
Gad7 Partial
Cssrs Moderate
Cssrs High Read Only
Cssrs No Risk
Usage
<PsychRatingScales defaultAnswers={{ phq9: [2, 2, 1, 2, 1, 1, 1, 0, 1] }} history={[{ date: "08/01/2026", phq9: 17, gad7: 13 }]} />
When to use
- Primary care and behavioral health screening, measurement-based care at each visit.
When not to use
- Diagnosis: a score is a screen.
- A full C-SSRS lifetime and since-last-visit interview.
Variants and states
| Variant | What it is |
|---|---|
| PHQ-9 | Nine items 0 to 3, bands minimal, mild, moderate, moderately severe, severe; change since last score. |
| GAD-7 | Seven items, bands minimal, mild, moderate, severe. |
| incomplete | "n of 9 answered" until every item has an answer; no band before that. |
| item 9 positive | Error Alert that opens the C-SSRS tab; the item row turns red. |
| C-SSRS screen | Questions 3 to 5 show only after a yes to 2; the 3 month question only after a yes to 6. |
| risk | None (success), low: give resources (info), moderate: safety plan and follow-up in 24 to 72 hours (warning), high: do not leave alone, crisis team (error). |
| history | Earlier scores and risk levels. |
| readOnly | Answers locked. |
Clinical values
Every number goes through the shared clinical value rules (CareOS.fmt and ClinicalValue from the clinical-values card): tabular digits, the unit always shown, a fixed precision per measure, the reference range in the tooltip, and H, L or critical flags. Medication amounts follow the ISMP dose style through fmt.doseNumber: rounded to the stated precision, then shown with no trailing zero (5 mg, never 5.0 mg) and a leading zero (0.5 mL). The specialty measures this card adds sit in CareOS.specialty.MEAS with their precision: scores whole points; change is signed. Ranges in the previews are sample values for the design system, not clinical guidance; a real deployment passes its own.
Accessibility
- Answers are radio groups named by the question.
- The score and the risk level update in a live region.
- Risk is a word badge and an Alert with role alert at high risk.
Do and don't
- Do: Run the C-SSRS screen the same visit when item 9 is above 0.
- Do: Record who was told about high risk and when.
- Don't: Show a band before every item is answered.
- Don't: Let the patient leave before a high-risk screen is acted on.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
answers | PsychAnswers | uncontrolled | Answers (controlled) |
defaultAnswers | PsychAnswers | {} | First answers (uncontrolled) {phq9?, gad7?, cssrs?} |
onAnswersChange | (answers: PsychAnswers) => void | none | Called with every answer change |
tab | PsychScaleTab | uncontrolled | Tab shown (controlled) |
defaultTab | PsychScaleTab | 'phq9' | First tab (uncontrolled): 'phq9' | 'gad7' | 'cssrs' |
onTabChange | (tab: PsychScaleTab) => void | none | Called with the new tab |
history | ReadonlyArray<PsychHistoryEntry> | [] | Earlier scores, oldest first |
title | string | 'Rating scales' | Card title |
subtitle | string | none | Line under the title |
readOnly | boolean | false | Locks the answers |
onCallCrisisTeam | () => void | none | Call Crisis Team action (high risk) |
onStartSafetyPlan | () => void | none | Start Safety Plan action (moderate or high risk) |
rangeContext | RangeContextId | the global context, else 'outpatient' | Which shared reference range flags use; the lab range on a result still wins |
Also accepts native attributes, including defaultChecked, defaultValue, autoFocus, plus className and event handlers on the root element.
Angular, Vue and HTML
Register the elements once (Angular guide), then use <co-psych-rating-scales>. Attributes take strings; arrays and objects are set as properties (Angular [prop], Vue :prop) or as JSON attributes. Callbacks are DOM events with the value in event.detail.
<co-psych-rating-scales tab="…" default-tab="…" [answers]="answers" (co-answers-change)="onAnswersChange($event.detail)"></co-psych-rating-scales>
| Kind | Name | Description |
|---|---|---|
| property / JSON attribute | answers | Answers (controlled); default uncontrolled |
| property / JSON attribute | default-answers / defaultAnswers | First answers (uncontrolled) {phq9?, gad7?, cssrs?}; default {} |
| attribute | tab | Tab shown (controlled); default uncontrolled |
| attribute | default-tab / defaultTab | First tab (uncontrolled): 'phq9' | 'gad7' | 'cssrs'; default 'phq9' |
| property / JSON attribute | history | Earlier scores, oldest first; default [] |
| attribute | title | Card title; default 'Rating scales' |
| attribute | subtitle | Line under the title; default none |
| attribute | read-only / readOnly | Locks the answers; default false |
| attribute | range-context / rangeContext | Which shared reference range flags use; the lab range on a result still wins; default the global context, else 'outpatient' |
| attribute | default-checked / defaultChecked | |
| property / JSON attribute | default-value / defaultValue | |
| attribute | auto-focus / autoFocus | |
| event | co-answers-change | Called with every answer change; default none (React: onAnswersChange) |
| event | co-tab-change | Called with the new tab; default none (React: onTabChange) |
| event | co-call-crisis-team | Call Crisis Team action (high risk); default none (React: onCallCrisisTeam) |
| event | co-start-safety-plan | Start Safety Plan action (moderate or high risk); default none (React: onStartSafetyPlan) |