---
updatedAt: 2026-10-06T20:39:29.000Z
agentTools:
  projectIndex: https://docs.photon.health/llms.txt
---

# Elements

**Photon Elements** are a set of prebuilt UI-components that can be used to add prescribing functionality into any web-based clinical tool.

Elements are built using [WebComponent technology](https://www.webcomponents.org/introduction) and can be used in any frontend app - regardless of framework. Elements do not use outdated `iframe` technology!

Elements automatically handle authentication and ensure that only authorized prescribers can send prescriptions. The UI is designed to be responsive across various screen sizes.

<Image src="https://files.readme.io/059e5d7-Screen_Shot_2023-01-27_at_6.56.02_PM.png" alt="1708" align="center" caption="This UI can be embedded directly in your clinical app." />

```html
<photon-client 
  id="YOUR_CLIENT_ID"
  org="YOUR_ORG_ID"
>
  <photon-prescribe-workflow/>
</photon-client>
```

## Get Started

First install our elements package from NPM:

```shell
npm i @photonhealth/elements
```

If using a framework like React, you'll need to [dynamically import](https://javascript.info/modules-dynamic-imports#the-import-expression) the package. This will register the custom elements with the browser's `CustomElementRegistry`.

```javascript
import("@photonhealth/elements")
```

See [this repository](https://github.com/Photon-Health/react-elements-demo) for a demonstration of using the elements within a React app.

## Client Element

Next, add the `photon-client` element toward the top level of your application.

```html
<photon-client
  id="your_client_id"
  org="your_org_id"
  redirect-uri="https://localhost:3000"
  dev-mode="true"
>
  <!-- nested photon elements -->
</photon-client>
```

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Property
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `id`
      </td>

      <td>
        The public ID registered to your application (with whitelisted URLs)
      </td>
    </tr>

    <tr>
      <td>
        `org`
      </td>

      <td>
        The Photon organization ID associated with your account
      </td>
    </tr>

    <tr>
      <td>
        `auto-login`
      </td>

      <td>
        Optional, defaults to "false". Set this to `auto-login="true"` to trigger automatically login on page load if the user is unauthenticated
      </td>
    </tr>

    <tr>
      <td>
        `redirect-uri`
      </td>

      <td>
        Optional. Specifies where to redirect the user after a successful login. This needs to match a configured Callback URL. For example, `https://example.com` or `https://example.com/prescribe`.

        You can however incorporate a strategy that handles a query parameter such as `https://example.com?redirect=user%2F1234%2Fprescribe`. Note that the `<photon-client>` will also merge a separate query parameter `photon=true` for internal checks.

        Working locally is possible if the URL, e.g. `localhost:3000`, is in your configured Callback URLs.
      </td>
    </tr>

    <tr>
      <td>
        `redirect-path`
      </td>

      <td>
        Optional. Reroutes to a path after login returns the user to the `redirect-uri`. An example redirect path is `/user/1234/prescribe`. Any existing path on `redirect-uri` will be **replaced**, not appended to.

        This will only work if the `<photon-client>` element exists at the `redirect-uri` base path.
      </td>
    </tr>

    <tr>
      <td>
        `dev-mode`
      </td>

      <td>
        Optional. When working locally set this to `"true"`in order to point our service at our staging service `neutron` rather than our production services at `photon`
      </td>
    </tr>
  </tbody>
</Table>

These values can be found in the [settings page of the Photon App](https://app.photon.health/settings), or in the [Sandbox App](https://app.neutron.health/settings). All `photon-` elements must be contained within the `photon-client` to function correctly.

If you're unable to put the `photon-client` at the root of your domain, then the property `redirect-path` will not work. However you can pass a query parameter to the `redirect-uri` property such as `https://localhost:3000?redirect=user/1234` and then handle the redirect with your own application logic.

Check out our [example repo](https://github.com/Photon-Health/react-elements-demo) that shows how to handle the authentication redirect. The `main` branch shows how to use a query string to redirect and the `root` branch shows how to use the `photon-client` at root with the `redirect-path`.

## Prescribe Element

The `photon-prescribe-workflow` can be added anywhere within the `photon-client` and renders a basic prescribe workflow. It accepts the following props:

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Property
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `patient-id`
      </td>

      <td>
        ID of the patient receiving the prescription.
      </td>
    </tr>

    <tr>
      <td>
        `template-ids`
      </td>

      <td>
        Templates that should be pre-selected.
      </td>
    </tr>

    <tr>
      <td>
        `template-overrides`
      </td>

      <td>
        When adding `template-ids`, this attribute allows for overriding specific fields on the template. The overrides are a JSON-stringified object where the keys are template IDs and the values are the override specifications:

        ```html
        <photon-prescribe-workflow  
           template-ids="tmp_01H5JB37PPK9F64RE3QQ52WD7M,tmp_01GQJDV39GPEJ03BATZV1X0SRJ"  
           template-overrides='{"tmp_01H5JB37PPK9F64RE3QQ52WD7M": {"instructions": "these instructions are overriding the previous instructions", "fillsAllowed": 200}}'  
        />
        ```

        The possible overrides are:

        ```typescript
        type TemplateOverrides = {
          [templateId: string]: {
            externalId?: string;
            dispenseQuantity?: number;
            dispenseUnit?: string;
            dispenseAsWritten?: boolean;
            fillsAllowed?: number;
            daysSupply?: number;
            instructions?: string;
            notes?: string;
          };
        };
        ```
      </td>
    </tr>

    <tr>
      <td>
        `prescription-ids`
      </td>

      <td>
        Prescriptions that should be pre-selected. These prescriptions will not be directly edited, they will be duplicated to create new draft prescriptions.&#x20;
      </td>
    </tr>

    <tr>
      <td>
        prescription-overrides
      </td>

      <td>
        When adding `prescription-ids`, this attribute allows for overriding specific fields on the prescription. The overrides are a JSON-stringified object where the keys are prescription IDs and the values are the override specifications:

        ```html
        <photon-prescribe-workflow  
           prescription-ids="rx_01H5JB37PPK9F64RE3QQ52WD7M,rx_01GQJDV39GPEJ03BATZV1X0SRJ"  
           prescription-overrides='{"rx_01H5JB37PPK9F64RE3QQ52WD7M": {"instructions": "these instructions are overriding the previous instructions"}}'  
          />
        ```

        The possible overrides are:

        ```typescript
        type PrescriptionOverrides = {
          [prescriptionId: string]: {
            externalId?: string;
            treatmentId?: string;
            dispenseQuantity?: number;
            dispenseUnit?: string;
            dispenseAsWritten?: boolean;
            fillsAllowed?: number;
            daysSupply?: number;
            instructions?: string;
            notes?: string;
            // ISO string or date string in format ex. 2026-10-02
            doNotFillBeforeDate?: string;
          }
        }
        ```
      </td>
    </tr>

    <tr>
      <td>
        disable-list
      </td>

      <td>
        A list of Photon medication and treatment IDs that should not be prescribed. An optional reason is presented to prescribers during treatment search to explain the disabled treatment.<br />

        ```typescript
        type DisabledMedicationItem = {
          treatmentIds: string[];
          reason?: string;
        };

        type DisableList = DisabledMedicationItem[];
        ```

        ```html
        <photon-prescribe-workflow
            enable-order="true"
            disable-list='[{"treatmentIds": ["med_01J6ZE5RSPDRXZRX7SEFHJSMDB"], "reason": "Not covered by patient insurance"}, {"treatmentIds": ["med_01J6ZE5RTEB5FK0CES2DDQWYV2"], "reason": "Too expensive"}]'
        ></photon-prescribe-workflow>
        ```
      </td>
    </tr>

    <tr>
      <td>
        allow-off-catalog-search
      </td>

      <td>
        Set to "false" to only allow prescribing treatments from the organization catalog, organization templates, and personal templates.
      </td>
    </tr>

    <tr>
      <td>
        `initial-prescriptions`
      </td>

      <td>
        An JSON-stringified array of input values that will be used to create draft prescriptions, without the need to pre-select templates or existing prescription. Prescribers will still be able to edit or delete these drafts.

        ```html
        <photon-prescribe-workflow
          initial-prescriptions='[{"externalId": "ext_initial_1", "treatmentId": "med_01J6ZE5RSPDRXZRX7SEFHJSMDB", "dispenseQuantity": 60, "dispenseUnit": "Tablet", "dispenseAsWritten": true, "fillsAllowed": 3, "daysSupply": 30, "instructions": "Take two tablets by mouth twice daily", "notes": "Initial prescription test note", "doNotFillBeforeDate": "2027-01-15"}]'
        />
        ```

        The input shape is:

        ```typescript
        type InitialPrescriptionInput = {
            treatmentId: string;
            dispenseQuantity: number;
            dispenseUnit: string;
            fillsAllowed: number;
            daysSupply: number;
            instructions: string;
            externalId?: string;
            dispenseAsWritten?: boolean;
            notes?: string;
            doNotFillBeforeDate?: string;
        }
        ```
      </td>
    </tr>

    <tr>
      <td>
        `additional-notes`
      </td>

      <td>
        Setting this parameter will append the string to each draft prescription's notes, including draft prescriptions created by `template-ids`, `prescription-ids`, and `initial-prescriptions`. Prescribers can still edit these notes.&#x20;
      </td>
    </tr>

    <tr>
      <td>
        `enable-order`
      </td>

      <td>
        Boolean that enables the creation of an order at the same time as a prescription. When this flag is set with nothing else, a pharmacy selection card will default to a "Local Pickup" option.
      </td>
    </tr>

    <tr>
      <td>
        `enable-send-to-patient`
      </td>

      <td>
        Prerequisite `enable-order` set to `true`.

        Boolean that allows prescribers to send patients the option to set their own pharmacy. Adds the "Send to Patient" tab to pharmacy selection.
      </td>
    </tr>

    <tr>
      <td>
        `enable-local-pickup`
      </td>

      <td>
        Prerequisite `enable-order` set to `true`.

        Boolean that allows prescribers to set the patient's pharmacy for them. Adds the "Local Pickup" tab to pharmacy selection.
      </td>
    </tr>

    <tr>
      <td>
        `enable-delivery-pharmacies`
      </td>

      <td>
        Prerequisite `enable-order` set to `true`.

        Boolean that allows prescribers to send the prescription to a mail order pharmacy. Adds the "Mail Order" tab to pharmacy selection.
      </td>
    </tr>

    <tr>
      <td>
        `enable-coverage-check`
      </td>

      <td>
        Boolean that allows a patient's insurance coverage to be checked for prescriptions added in the prescribe workflow.

        For a selected or nearby pharmacy, the prescriber will be shown a medication covered status, therapeutic and pharmacy alternatives, Prior Authorization warnings, and an estimated copay.

        Requires patient benefit data to be on file with Photon. Please reach out to us for assistance configuring this.
      </td>
    </tr>

    <tr>
      <td>
        `mail-order-ids`
      </td>

      <td>
        Prerequisite `enable-order` set to `true`.

        Comma separated list of mail order pharmacy ids.
      </td>
    </tr>

    <tr>
      <td>
        `pharmacy-id`
      </td>

      <td>
        Prerequisite `enable-order` set to `true`.

        Sets a preselected pharmacy.
      </td>
    </tr>

    <tr>
      <td>
        `hide-templates`
      </td>

      <td>
        Optional boolean, defaults to `false`. Setting this flag to `true` will remove the ability for prescribers to save personal templates.
      </td>
    </tr>

    <tr>
      <td>
        `hide-submit`
      </td>

      <td>
        Optional boolean, defaults to `false`. Setting this flag to `true` will remove either the "Save Prescriptions" or "Send Order" button depending on your configuration.
      </td>
    </tr>

    <tr>
      <td>
        `hide-patient-card`
      </td>

      <td>
        Optional boolean, defaults to `false`. Setting this flag to `true` will hide the patient card from the prescribe flow.
      </td>
    </tr>

    <tr>
      <td>
        `address`
      </td>

      <td>
        Optional, setting `address` will override the prescriber's ability to manually set the the patient's address when `enable-order` is set to `true`. The `address` object takes this shape:

        ```typescript
        type Address = {
          city: string;
          postalCode: string;
          state: string;
          street1: string;
          street2?: string;
          country?: string;
        }
        ```

        Please note that web components accept attributes as strings. Therefore, when passing an object as a prop, you must stringify it first. Here's an example of how to pass the address object to a web component: `address={JSON.stringify(address)}`
      </td>
    </tr>

    <tr>
      <td>
        `supervisor`
      </td>

      <td>
        A JSON-stringified object containing a supervising physician to assign to the order.

        ```html
        <photon-prescribe-workflow
        supervisor='{"firstName":"Jane","lastName":"Doe","address":{"country":"US","city":"Brooklyn","postalCode":"11120","state":"NY","street1":"201 N 8th St","street2":null},"npi":"1234567890","phone":"+11234567890"}'
        />
        ```

        The input shape is:

        ```typescript
        type SupervisorInput = {
          firstName: string;
          lastName: string;
          npi: string;
          address: AddressInput;
          // Defaults to org phone
          phone?: string;
        };

        // Their practice address
        type AddressInput = {
          street1: string;
          street2?: string;
          city: string;
          state: string;
          postalCode: string;
          country?: string;
        }
        ```
      </td>
    </tr>

    <tr>
      <td>
        `external-order-id`
      </td>

      <td>
        Optional ID that can be associated with the order being created.
      </td>
    </tr>

    <tr>
      <td>
        `enable-med-history`
      </td>

      <td>
        Optional Boolean, enables a card in the prescribe flow that shows the selected patient's recent prescriptions.
      </td>
    </tr>

    <tr>
      <td>
        `enable-med-history-links`
      </td>

      <td>
        Optional Boolean, enables a link on the medication row that directs to Photon's Prescriber Portal.
      </td>
    </tr>

    <tr>
      <td>
        `enable-med-history-refill-button`
      </td>

      <td>
        Optional Boolean, enables a button to add an existing prescription to the order.
      </td>
    </tr>

    <tr>
      <td>
        `enable-combine-and-duplicate`
      </td>

      <td>
        Optional Boolean, enables a recent orders card that shows prescriptions recently sent. If they seem to be duplicate, we'll notify the prescriber. Also, if the order hasn't been sent to a pharmacy yet we'll attempt to combine the orders into a single order to make for better patient communication.
      </td>
    </tr>

    <tr>
      <td>
        `weight`
      </td>

      <td>
        The weight of the patient, number.
      </td>
    </tr>

    <tr>
      <td>
        `weight-unit`
      </td>

      <td>
        The weight unit, either `lbs` or `kg`.
      </td>
    </tr>
  </tbody>
</Table>

Here's an example of a Photon Element that enables orders to a preselected pharmacy:

```html
<photon-prescribe-workflow
  patient-id="pat_9876zyxw"
  enable-order="true"
  pharmacy-id="phr_1234abcd"
/>
```

Alternatively, here's how you would enable an prescribe element with all of the pharmacy selection options:

```html HTML
<photon-prescribe-workflow
  patient-id="pat_01GQ0XFBHSH3YXN936A2D2SD7Y"
  enable-order="true"
  enable-send-to-patient="true"
  enable-local-pickup="true"
  mail-order-ids="phr_01GA9HPVBVJ0E65P819FD881N0"
/>
```

<Image src="https://files.readme.io/89db336-image.png" alt="The above code will enable a similar Pharmacy Select card." align="center" width="400px" caption="The above code will enable a similar Pharmacy Select card." />

### Events

Event payloads will be on `detail`.

```javascript
document.addEventListener('photon-order-created', (e) => {
  console.log('Order Info: ', e.detail.order);
});
```

| Event Name                          | Description                                                                                                                                                                                                                          | Detail                              |
| :---------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------- |
| `photon-prescriptions-created`      | Triggered when prescriptions have been successfully created.                                                                                                                                                                         | `{ prescriptions: Prescription[] }` |
| `photon-order-created`              | If the `enable-order` flag is set and the prescriber selects to "Send Order", this will trigger when prescriptions and an order are successfully created.                                                                            | `{ order: Order }`                  |
| `photon-prescriptions-error`        | Triggered when there are errors creating prescriptions.                                                                                                                                                                              | `{ errors: GraphQLError[] }`        |
| `photon-order-error`                | Triggered when there are errors creating the order.                                                                                                                                                                                  | `{ errors: GraphQLError[] }`        |
| `photon-draft-prescription-created` | Triggered when a draft prescription is added to the "Pending Order" card.                                                                                                                                                            | `{ draft }`                         |
| `photon-draft-prescription-deleted` | Triggered when a draft prescription has been removed from the pending orders section. Returns the deleted prescription.                                                                                                              | `{ prescription }`                  |
| `photon-order-combined`             | Triggered when a draft prescription has been combined into an existing order. Emitted instead of `photon-order-created` when `enable-combine-and-duplicate="true"` and the user chooses to combine a new order with an existing one. | `{ orderId }`                       |

## Medical History Component

<Image src="https://files.readme.io/a6759e1d355cb06dd6c261f370f55e22c1a1a7da64ecbf857a4a4465b53a197a-Screenshot_2025-03-24_at_4.42.19_PM.png" align="center" width="512px" />

The `photon-med-history` can be added anywhere within the `photon-client` and renders a list of the patients most recent prescriptions. It accepts the following props:

| Property     | Description                                        |
| :----------- | :------------------------------------------------- |
| `patient-id` | Accepts a patient's Photon ID or their external ID |

```html HTML
<photon-med-history patient-id="123abc"></photon-med-history>
```

<br />

## Framework Support

Below you'll find example integrations for React, Angular, and Vue.

```javascript React
import("@photonhealth/elements").catch(() => {});
import { createRef, useEffect, useState } from "react";

function App() {
  const photonPrescribeRef = createRef();

  useEffect(() => {
    const log = () => {
      console.log("treatment prescribed!");
    }
    if (photonPrescribeRef.current) {
      photonPrescribeRef.current.addEventListener("photon-prescribe-success", log);
      const removal = () => photonPrescribeRef.current.removeEventListener("photon-prescribe-success", log);
      return () => removal()
    }
  }, [])

  return (
    <div>
      <photon-client
        id="CLIENT_ID"
        org="ORGANIZATION_ID"
      >
         <photon-prescribe-workflow ref={photonPrescribeRef} />
      </photon-client>
    </div>
  );
}

export default App;
```
```javascript Angular
import { Component } from '@angular/core';
import('@photonhealth/webcomponents').catch(() => {});

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  title = 'my-app';

  public log() {
    console.log("treatment prescribed!");
  }
}

...

<div>
  <photon-client
      id="CLIENT_ID"
      org="ORGANIZATION_ID"
    >
      <photon-prescribe-workflow (photon-prescribe-success)="log()"></photon-prescribe-workflow>
    </photon-client>
</div>
```
```javascript Vue
<script setup lang="ts">
import("@photonhealth/webcomponents").catch((err) => {});

const log = () => {
  console.log("treatment prescribed!");
}
</script>

<template>
  <div>
    <photon-client
      id="CLIENT_ID"
      org="ORGANIZATION_ID"
    >
      <photon-prescribe-workflow v-on:photon-prescribe-success="log()" />
    </photon-client>
  </div>
</template>
```