# Custom elements

Custom events are *synthetic events* in Javascript that can be dispatched to our SDK.

Use custom events to communicate with our custom elements to wrap your code and handle all logic, analytics and API requests.

* [didomi-container-headless](#didomi-container-headless)
* [didomi-if-not-authenticated](#didomi-if-not-authenticated)
* [didomi-if-authenticated](#didomi-if-authenticated)
* [didomi-auth-headless](#didomi-auth-headless)
* [didomi-consent-asked](#didomi-consent-asked)
* [didomi-consent-receiver](#didomi-consent-receiver)
* [didomi-pending-consent-receiver](#didomi-pending-consent-receiver)
* [didomi-component-content](#didomi-component-content)
* [didomi-entity-content](#didomi-entity-content)

#### didomi-container-headless

Add the custom element `didomi-container-headless` to wrap your widget. This component should wrap all other widget related elements as it contains a boundary intercepting events and communicating with our API.

| Properties | Description      |
| ---------- | ---------------- |
| `id`       | ID of the widget |

```html
<didomi-container-headless id="widgetId">
  // Add your HTML here
</didomi-container-headless>
```

#### didomi-if-not-authenticated

To display content when the end-user is not logged into the Didomi system, add the custom element `didomi-if-not-authenticated`.

| Properties     | Description      |
| -------------- | ---------------- |
| `container-id` | ID of the widget |

```html
<didomi-if-not-authenticated container-id="widgetId">
	<p> I am displayed when end-user is not authenticated </p>
</didomi-if-not-authenticated>
```

#### didomi-if-authenticated

To display content only when the end-user is logged into the Didomi system, add the custom element `didomi-if-authenticated`.

| Properties     | Description      |
| -------------- | ---------------- |
| `container-id` | ID of the widget |

```html
<didomi-if-authenticated container-id="widgetId">
  <p> I am displayed when end-user is authenticated </p>
</didomi-if-authenticated>
```

#### didomi-auth-headless

Add the custom element `didomi-auth-headless` to wrap a login form and handle end-user authentication.

To request authentication, you will need to create and dispatch the custom event `didomi:send-authentication`.

| Properties     | Description      |
| -------------- | ---------------- |
| `container-id` | ID of the widget |

```html
<didomi-auth-headless container-id="widgetId">
  // Add your auth form here
</didomi-auth-headless>
```

This custom element takes care of sending the `authentication.asked` and `authentication.sent` analytic events.

#### didomi-consent-asked

To send `consent.asked` analytics event, add the custom element `didomi-consent-asked`.

Please make sure to only add this component once in your page to avoid sending multiple events.

| Prop           | Description      |
| -------------- | ---------------- |
| `container-id` | ID of the widget |

```html
<didomi-consent-asked container-id="widgetId"></didomi-consent-asked>
```

#### didomi-consent-receiver

To send end-users' choices through our SDK upon click, wrap your entities in the custom element `didomi-consent-receiver`.

| Properties     | Description      |
| -------------- | ---------------- |
| `container-id` | ID of the widget |

```html
<didomi-consent-receiver container-id="widgetId">
    // Add your input/checkbox/radio... here
</didomi-consent-receiver>
```

To save end-users' choices through our SDK upon clicking, create and dispatch the custom event `didomi:set-consents`.

This custom element takes care of sending the `consent.given` analytic event.

#### didomi-pending-consent-receiver

To store end-users' choices in the application state before saving them, wrap your entities in the custom element `didomi-pending-consent-receiver`, create and dispatch the custom event `didomi:set-pending-consents`.

Within the `didomi-pending-consent-receiver`, you will also need to add a save button, create and dispatch the custom event `didomi:save-pending-consents` to save the consent state in our database.

| Prop           | Description      |
| -------------- | ---------------- |
| `container-id` | ID of the widget |

```html
<didomi-pending-consent-receiver container-id="widgetId">
  // Add your input/checkbox/radio... as well as your save button here
</didomi-consent-receiver>
```

This custom element takes care of sending the `consent.given` analytic event.

#### didomi-component-content

To display a content option of a component of your widget, use the custom element `didomi-component-content`.

| Properties           | Description                                                                                                                                                                         |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `container-id`       | ID of the widget                                                                                                                                                                    |
| `component-id`       | ID of the layout-component                                                                                                                                                          |
| `component-property` | Property of the layout-component. For example `saveButton.text.content` (if it has been edited at the layout-component level) or `icon.src` to get the URL of the preference value. |

```html
<didomi-component-content
    container-id="widgetId"
    component-id="componentId"
    component-property="pathOfProperty"
></didomi-component-content>
```

#### didomi-entity-content

To display an entity of your widget, such as the title or description from a purpose or preference, use the custom element `didomi-component-content`.

| Properties               | Description                                                                                                                                                                                  |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `container-id`           | ID of the widget                                                                                                                                                                             |
| `entity-id`              | ID of the selected purpose, selected preference or preference value. You can easily find them in the Configuration Tree section on the Console.                                              |
| `entity-property`        | This property determines which content of the entity object should be displayed. It can be `name` or `description`.                                                                          |
| `entity-type`            | Specify the type of property. It can be either `purpose`, `preference` or `preference-value`.                                                                                                |
| `with-component-content` | This property is used to determine whether to override the entity content with the layout component one set a widget level, if any (`true`), or to display the entity content (`undefined`). |

```html
<didomi-entity-content
    container-id="widgetId"
    entity-id="entityId"
    entity-property="pathOfProperty"
    entity-type="entityType"
    with-component-content="true"
></didomi-entity-content>
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.didomi.io/api-and-platform/widgets/privacy-widgets/headless-widgets/custom-elements.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.