ValueSet $expand | Medplum

On this page

The $expand operation returns all codes contained in a ValueSet, making it ideal for populating dropdown menus, typeahead search fields, and code pickers in clinical applications. Instead of storing and managing large code lists client-side, you can dynamically fetch the allowed values for any coded field.

This operation supports filtering and pagination, enabling responsive user interfaces that can search through thousands of codes (like SNOMED CT or LOINC) while only loading relevant results as the user types.

Use Cases

Dropdown Population: Fetch all valid options for coded fields like gender, marital status, or allergy types
Typeahead Search: Power autocomplete fields that search through large code systems as users type
Form Builders: Dynamically load code options when rendering questionnaires or data entry forms
Code Picker Components: Build searchable code selection interfaces with pagination support
Validation UI: Show users the valid options when they've entered an invalid code

Invoke the `$expand` operation

[base]/ValueSet/$expand

Parameters

Name	Type	Description	Required
`url`	`string`	The URL of the value set to expand	Yes
`filter`	`string`	A filter to apply to the value set	No
`offset`	`number`	The offset to start the expansion	No
`count`	`number`	The number of results to return	No
`displayLanguage`	`string`	The language code to search with `filter`	No
`excludeNotForUI`	`boolean`	Exclude abstract concepts that shouldn't be displayed in user interfaces	No
`includeDesignations`	`boolean`	Include translations and synonyms (designations) in the expansion results	No
`valueSet`	`ValueSet`	An inline ValueSet resource to expand (alternative to providing a URL)	No

Output

The result of the expansion as a ValueSet resource. The results of the expansion operation are in the ValueSet.expansion field.

Examples

Query all values for a ValueSet:

curl 'https://api.medplum.com/fhir/R4/ValueSet/$expand?url=http%3A%2F%2Fhl7.org%2Ffhir%2FValueSet%2Fadministrative-gender' \
  -H "Content-Type: application/fhir+json" \
  -H "Authorization: Bearer MY_ACCESS_TOKEN"

{
  "resourceType": "ValueSet",
  "url": "http://hl7.org/fhir/ValueSet/administrative-gender",
  "expansion": {
    "offset": 0,
    "contains": [
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "female",
        "display": "Female"
      },
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "male",
        "display": "Male"
      },
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "other",
        "display": "Other"
      },
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "unknown",
        "display": "Unknown"
      }
    ]
  }
}

Filter by search string:

curl 'https://api.medplum.com/fhir/R4/ValueSet/$expand?url=http%3A%2F%2Fhl7.org%2Ffhir%2FValueSet%2Fadministrative-gender&filter=f' \
  -H "Content-Type: application/fhir+json" \
  -H "Authorization: Bearer MY_ACCESS_TOKEN"

{
  "resourceType": "ValueSet",
  "url": "http://hl7.org/fhir/ValueSet/administrative-gender",
  "expansion": {
    "offset": 0,
    "contains": [
      {
        "system": "http://hl7.org/fhir/administrative-gender",
        "code": "female",
        "display": "Female"
      }
    ]
  }
}

The MedplumClient TypeScript class provides a valueSetExpand convenience method:

const url = 'http://hl7.org/fhir/ValueSet/administrative-gender';

const input = 'f';

const result = await medplum.valueSetExpand({ url, filter: input });

Use Cases

Invoke the $expand operation

Parameters

Output

Examples

Invoke the `$expand` operation