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

```text
[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](https://developer.mozilla.org/en-US/docs/Glossary/BCP_47_language_tag) 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:

```bash
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"
```

```json
{
  "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:

```bash
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"
```

```json
{
  "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](/content/docs/sdk/core.medplumclient) TypeScript class provides a `valueSetExpand` convenience method:

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

const input = 'f';

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