Configuration

CareConekt.CodeSystems.configure(settings)

Call this once before bind(). Sets global configuration for all widget instances.

CareConekt.CodeSystems.configure({
  // Required
  apiBaseUrl: "https://gw.careconekt.net/api/codesystems-search",
  apiKey: "ck_your_api_key",

  // Optional
  tenantId: "tenant-uuid",
  defaultCodeSystem: "icd10cm",
  debounceMs: 300,
  autocompleteMinChars: 2,
  searchResultsSize: 20,
  theme: "light",

  // Callbacks
  onSelect: function (concept, instanceId) {},
  onSearchStart: function (query, instanceId) {},
  onSearchEnd: function (total, instanceId) {},
  onError: function (error, instanceId) {},
});

Settings Reference

Required

apiBaseUrl

Type: string

The CareConekt API base URL for code system search.

Value: "https://gw.careconekt.net/api/codesystems-search"

apiKey

Type: string

Your CareConekt API key (prefixed with ck_). Sent as the X-API-Key header on every request. Obtain this from your organization’s admin portal.

Optional

tenantId

Type: string | null

Default: null

Tenant UUID for multi-tenant search. When set, all API calls include tenant_id as a query parameter, scoping results to the tenant’s code systems.

defaultCodeSystem

Type: string | null

Default: null

Pre-filter searches to a specific code system by slug (e.g., "icd10cm", "cpt", "loinc"). Users can change this via the code system dropdown. Pass null to search across all code systems.

debounceMs

Type: number

Default: 300

Milliseconds to wait after the user stops typing before firing an autocomplete request. Lower values feel more responsive but generate more API calls.

autocompleteMinChars

Type: number

Default: 2

Minimum characters before autocomplete suggestions appear. Set higher to reduce noise on short inputs.

searchResultsSize

Type: number

Default: 20

Number of results per page for full search (triggered by pressing Enter). Valid range: 1–100.

theme

Type: "light" | "dark" | "auto"

Default: "light"

Colour theme of the widget. "auto" follows the visitor’s system preference. Does not affect the input element, which is part of your page.

Callbacks

All callbacks receive the instanceId as the second argument, so you can distinguish which widget instance fired the event.

onSelect(concept, instanceId)

Fired when the user selects a concept — from autocomplete, search results, or the detail panel.

The concept object varies by source:

From autocomplete:

{
  code: "E11.9",
  display: "Type 2 diabetes mellitus without complications",
  code_system_slug: "icd10cm",
  code_system_name: "ICD10-CM"
}

From search results:

{
  concept_id: "icd10cm-E11.9",
  code: "E11.9",
  display: "Type 2 diabetes mellitus without complications",
  code_system_slug: "icd10cm",
  code_system_name: "ICD10-CM",
  status: "active",
  score: 12.5,
  highlights: { display: ["Type 2 <em>diabetes</em> mellitus..."] }
}

From concept detail:

{
  concept_id: "icd10cm-E11.9",
  code: "E11.9",
  display: "Type 2 diabetes mellitus without complications",
  code_system_slug: "icd10cm",
  code_system_name: "ICD10-CM",
  version: "2024",
  status: "active",
  definition: "...",
  synonyms: ["DM2", "NIDDM"],
  parent_codes: ["E11"],
  child_codes: [],
  properties: {}
}

onSearchStart(query, instanceId)

Fired when a full search begins (user presses Enter). Use this to show loading indicators in your surrounding UI.

onSearchEnd(total, instanceId)

Fired when search results arrive. total is the total number of matching concepts (not just the current page).

onError(error, instanceId)

Fired on API errors. The error object has a .message property. Common errors:

• "Invalid API key" — the key is missing, mistyped or revoked

• "Access denied — check your subscription plan" — the plan does not include code system search

• "Rate limit exceeded — try again later" — the plan’s request limit was reached

• "API error: <status>" — other errors from the service (see Authentication)

Handler Methods

CareConekt.CodeSystems.bind(ino)

Initialize a widget instance. Finds the <input class="ccs-input" data-ccs-ino="..."> and <div class="ccs-window" data-ccs-ino="..."> elements, attaches Shadow DOM, and starts listening for user input.

CareConekt.CodeSystems.bind("1");

Throws if configure() hasn’t been called, or if the HTML elements aren’t found.

CareConekt.CodeSystems.clear(ino)

Clear the input, results, and selection for an instance.

CareConekt.CodeSystems.clear("1");

CareConekt.CodeSystems.destroy(ino)

Tear down an instance — removes event listeners, clears Shadow DOM content, and unregisters from the internal registry. The HTML elements remain in the page.

CareConekt.CodeSystems.destroy("1");

CareConekt.CodeSystems.getSelection(ino)

Returns the last selected concept object, or null if nothing has been selected.

const concept = CareConekt.CodeSystems.getSelection("1");
if (concept) {
  console.log(concept.code, concept.display);
}

CareConekt.CodeSystems.setCodeSystem(ino, slug)

Programmatically set the code system filter. Pass null to clear the filter.

CareConekt.CodeSystems.setCodeSystem("1", "cpt");  // Filter to CPT codes
CareConekt.CodeSystems.setCodeSystem("1", null);    // Search all systems

CareConekt.CodeSystems.search(ino, query)

Programmatically trigger a full search. Sets the input value and fires the search.

CareConekt.CodeSystems.search("1", "diabetes");

CareConekt.CodeSystems.version

Returns the widget version string.

console.log(CareConekt.CodeSystems.version); // "0.1.0"

Theming with CSS Custom Properties

Your page’s CSS cannot accidentally break the widget. To change its colours and shadow, set these CSS custom properties on the .ccs-window element; the widget picks them up in every theme:

.ccs-window[data-ccs-ino="1"] {
  --ccs-bg: #ffffff;
  --ccs-bg-hover: #f3f4f6;
  --ccs-bg-active: #e5e7eb;
  --ccs-text: #111827;
  --ccs-text-muted: #6b7280;
  --ccs-border: #d1d5db;
  --ccs-accent: #2563eb;
  --ccs-code-bg: #eff6ff;
  --ccs-code-text: #1e40af;
  --ccs-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}

The input element is in your page’s DOM — style it directly with your own CSS.