Usage Examples

`@openpronoun/core` API

Install the package:

npm install @openpronoun/core

`parse(input)`

Converts free-text input into a structured PronounPreference. Returns null for empty, whitespace-only, placeholder (N/A, TBD, -), or null input.

import { parse } from "@openpronoun/core";

parse("she/her");
// [{ subjective: "she", objective: "her", possessive_adjective: "her",
//    possessive_pronoun: "hers", reflexive: "herself" }]

parse("they/them, she/her");
// [{ subjective: "they", ... }, { subjective: "she", ... }]

parse("they/them/he/him");
// two sets — concatenation split:
// [{ subjective: "they", ... }, { subjective: "he", ... }]

parse("any pronouns");
// [{ type: "any" }]

parse("no pronouns");
// [{ type: "none" }]

parse("ask me");
// [{ type: "ask" }]

parse("prefer not to disclose");
// [{ type: "unspecified" }]

parse("she/her (professional contexts only)");
// [{ subjective: "she", ..., context: "professional contexts only" }]

parse("he/him or she/her, just not they/them");
// [{ subjective: "he", ... },
//  { subjective: "she", ... },
//  { subjective: "they", ..., exclude: true }]

parse("fox/foxs");
// [{ type: "custom", display: "fox/foxs" }]

parse("N/A");
// null

parse(null);
// null

`format(preference, options?)`

Converts a PronounPreference back into a display string.

import { parse, format } from "@openpronoun/core";

const pref = parse("she/her, they/them")!;

format(pref);
// "She/Her, They/Them"

format(pref, { form: "expanded" });
// "She/Her/Hers, They/Them/Theirs"

// Ranking: lower number = higher priority
const ranked = parse("she/her, they/them")!.map((e, i) => ({
  ...e,
  ranking: i === 0 ? 2 : 1,
}));
format(ranked);
// "They/Them, She/Her"

// Context is rendered in parentheses
format(parse("he/him (at work), they/them")!);
// "He/Him (at work), They/Them"

// Excluded sets are omitted from short display
format(parse("she/her, not they/them")!);
// "She/Her"

// Excluded sets surfaced in detailed display
format(parse("she/her, not they/them")!, { form: "detailed" });
// "She/Her (not They/Them)"

// Special types
format([{ type: "any" }]);             // "Any pronouns"
format([{ type: "none" }]);            // "No pronouns (use name)"
format([{ type: "ask" }]);             // "Ask me my pronouns"
format([{ type: "unspecified" }]);     // "Unspecified"

// Custom entries are displayed as entered (with capitalization)
format([{ type: "custom", display: "fae/faer" }]);
// "Fae/Faer"

`format` with privacy filtering

Entries with privacy level 1 or higher are hidden when audience is "public".

import { format } from "@openpronoun/core";

const pref = [
  { subjective: "she", objective: "her",
    possessive_adjective: "her", possessive_pronoun: "hers", reflexive: "herself",
    privacy: 0 },
  { subjective: "they", objective: "them",
    possessive_adjective: "their", possessive_pronoun: "theirs", reflexive: "themselves",
    privacy: 1 },
];

format(pref);                          // "She/Her, They/Them"
format(pref, { audience: "public" });  // "She/Her"

`validate`, `validateOrThrow`, `validationErrors`

import { validate, validateOrThrow, validationErrors } from "@openpronoun/core";

validate([{ subjective: "she", objective: "her",
            possessive_adjective: "her", possessive_pronoun: "hers",
            reflexive: "herself" }]);
// true

validate("she/her");
// false — raw strings are not a PronounPreference

validationErrors([{ subjective: "she" }]);
// ["objective: Required", "possessive_adjective: Required", ...]

validateOrThrow([{ type: "any" }]);
// [{ type: "any" }] — returns the value if valid, throws ZodError if not

`filterByAudience`

Strips entries the current audience is not allowed to see, based on the privacy field.

import { filterByAudience } from "@openpronoun/core";

const pref = [
  { subjective: "she", objective: "her",
    possessive_adjective: "her", possessive_pronoun: "hers",
    reflexive: "herself" },
  { subjective: "they", objective: "them",
    possessive_adjective: "their", possessive_pronoun: "theirs",
    reflexive: "themselves", privacy: 1 },
];

filterByAudience(pref, "public");
// [{ subjective: "she", ... }]  — they/them entry removed

filterByAudience(pref, "internal");
// both entries returned — only "public" triggers filtering

Constants

import {
  PRONOUN_DICTIONARY,
  FORM_TO_SET,
  SPECIAL_KEYWORDS,
  PLACEHOLDER_STRINGS,
  FILLER_PATTERNS,
} from "@openpronoun/core";

// All built-in English sets
PRONOUN_DICTIONARY.map((e) => `${e.subjective}/${e.objective}`);
// ["she/her", "he/him", "they/them", "it/it", "xe/xem", "ze/zir", ...]

// Reverse lookup: any form → its canonical set
FORM_TO_SET.get("him");
// { subjective: "he", objective: "him", ... }

FORM_TO_SET.get("theirs");
// { subjective: "they", objective: "them", ... }

// All recognized special-keyword phrases
SPECIAL_KEYWORDS.any;
// ["any", "any pronouns", "any/all", "all", "idc", ...]

SPECIAL_KEYWORDS.none;
// ["none", "no pronouns", "use my name", ...]

TypeScript types

import type {
  PronounPreference,
  PronounEntry,
  PronounSet,
  SpecialPreference,
  CustomEntry,
  FormatOptions,
  CanonicalEntry,
} from "@openpronoun/core";

// PronounPreference is PronounEntry[]
const pref: PronounPreference = [
  {
    subjective: "they",
    objective: "them",
    possessive_adjective: "their",
    possessive_pronoun: "theirs",
    reflexive: "themselves",
  },
];

// FormatOptions
const opts: FormatOptions = { form: "expanded", audience: "public" };

`@openpronoun/react` components

The React package builds on @openpronoun/core and provides ready-made, accessible components and hooks for collecting and displaying pronouns.

npm install @openpronoun/react

Components at a glance

Component	Purpose
`<PronounDisplay>`	Read-only display of one or more entries (text or badge mode)
`<PronounBadge>`	Single-entry pill badge, optionally removable
`<PronounSelector>`	Multi-select picker with drag-to-reorder and custom pronoun editor
`<PronounForm>`	All-in-one field: label + selector + helper text + preview
`<PronounDetailEditor>`	Form for entering all five pronoun forms manually
`<OriginalTextBadge>`	Shows the original freetext alongside structured output

Hooks

Hook	Purpose
`usePronounState`	Manages a `PronounEntry[]` list with add/remove/reorder
`usePronounParser`	Debounced live parsing of freetext into entries

Quick start

import { PronounForm } from "@openpronoun/react";

function ProfileForm() {
  const [pronouns, setPronouns] = useState([]);
  return (
    <PronounForm
      label="Pronouns"
      helperText="Sharing is optional — we use this to address you correctly."
      value={pronouns}
      onChange={setPronouns}
      showPreview
    />
  );
}

Display only

import { PronounDisplay } from "@openpronoun/react";

// Short: "She/Her, They/Them"
<PronounDisplay pronouns={user.pronouns} />

// Expanded: "She/Her/Hers"
<PronounDisplay format="long" pronouns={user.pronouns} />

// Badge pills
<PronounDisplay displayMode="badges" pronouns={user.pronouns} />

// Hides entries with privacy ≥ 1 (default: publicOnly=true)
<PronounDisplay publicOnly pronouns={user.pronouns} />

Theming and customization

Pass a partial theme object to override colors, fonts, border-radius, and spacing. Built-in presets: defaultTheme, darkTheme, plumecareTheme, memberDashboardTheme.

import { PronounSelector, darkTheme } from "@openpronoun/react";

<PronounSelector
  value={pronouns}
  onChange={setPronouns}
  theme={darkTheme}
/>

// Or supply a partial override (deep-merged with defaultTheme):
<PronounSelector
  value={pronouns}
  onChange={setPronouns}
  theme={{ colors: { primary: "#7c3aed" } }}
/>

Every component also accepts a classNames prop for granular CSS class injection on individual sub-elements:

<PronounSelector
  classNames={{
    root: "my-selector",
    tag: { container: "my-tag", label: "my-tag-label" },
    option: { groupLabel: "my-group" },
  }}
  value={pronouns}
  onChange={setPronouns}
/>

Live examples

React tab uses @openpronoun/react — click through Display, Selection, Form, Parser, and Themes to explore the full component library.

PronounDisplay — text mode

shortShe/Her, They/Them

long (expanded)She/Her/Hers

neopronounsXe/Xem

custom separatorShe/Her · They/Them

with examples ↓ (click pronoun)They/Them

PronounDisplay — badge modeShe/HerThey/Them

He/Him/HisThey/Them/Theirs

Special preferences (spec §D4)

anyAny pronouns

askAsk me

noneNo pronouns (use name)

unspecifiedUnspecified

Privacy filtering (spec §F4 — publicOnly)

publicOnly=true (default)She/Her

publicOnly=falseShe/Her, They/Them

They/them has privacy=1. Hidden in public context, visible when publicOnly=false.

Excluded sets (spec §F2a — omitted in short display)She/HerHe/him is excluded — not shown.

PronounBadge — standalone

She/HerThey/Them/TheirsAny pronounsHe/Him

Vue — @openpronoun/core

Short: She/Her, They/Them
Expanded: She/Her/Hers, They/Them/Theirs
Entries: 2

Svelte — @openpronoun/core

Short: She/Her, They/Them
Expanded: She/Her/Hers, They/Them/Theirs
Entries: 2

Solid — @openpronoun/core

Short: She/Her, They/Them
Expanded: She/Her/Hers, They/Them/Theirs
Entries: 2

Preact — @openpronoun/core

Short: She/Her, They/Them
Expanded: She/Her/Hers, They/Them/Theirs
Entries: 2

Alpine.js — @openpronoun/core (SSR)

Input: she/her, they/them
Short
Expanded
Entries

Alpine runs in the browser and can't import Node ESM directly — parsing happens at build time via Astro. For live re-parsing, proxy to an API route that calls @openpronoun/core server-side.

Vanilla JS — @openpronoun/core (SSR)

Input	Short	Expanded	#
`she/her, they/them`	She/Her, They/Them	She/Her/Hers, They/Them/Theirs	2
`any pronouns`	Any pronouns	Any pronouns	1
`xe/xem`	Xe/Xem	Xe/Xem/Xyrs	1
`he/him or she/her, just not they/them`	He/Him, She/Her	He/Him/His, She/Her/Hers	3

Rendered at build time — no JS bundle required. For interactive demos in plain JS, parse on the server and stream the result, or use one of the framework integrations above.

Usage Examples

@openpronoun/core API

parse(input)

format(preference, options?)

format with privacy filtering

validate, validateOrThrow, validationErrors

filterByAudience