> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# getWriteableElement()

Retrieves a reference to a writeable element container where custom HTML content can be injected into specific locations within the chat interface. Use this method to add custom notifications, images, carousels, banners, and other interactive content to enhance the chat experience.

## Syntax

```javascript theme={null}
instance.getWriteableElement(elementName);
```

## Parameters

<ParamField path="elementName" type="string" required>
  The name of the writeable element location. Must be one of the available writeable element names.
</ParamField>

### Available writeable element locations

| Element Name                | Location                 | Description                                                                                                                                                     |
| --------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `belowHeader`               | Below chat header        | Appears on a new line directly below the chat header. You can use for notifications, banners, or alerts.                                                        |
| `aboveInputBar`             | Above input area         | Positioned between the message area and the input field. Suitable for contextual information or quick actions.                                                  |
| `aboveWelcomeTitle`         | Above welcome message    | Displays in the main message body directly above the welcome message title.                                                                                     |
| `belowWelcomeStarters`      | Below starter prompts    | Appears in the main message body directly below the starter prompt cards.                                                                                       |
| `aiTooltipAfterDescription` | In AI disclaimer tooltip | Positioned within the AI disclaimer tooltip after the description content. For more information, see [`aiTooltipAfterDescription`](#aiTooltipAfterDescription). |
| `chatWelcomeComponent`      | Center of chat area      | Displays in the center of the chat interface, overlaying the main content area. For more information, see [`chatWelcomeComponent`](#chatWelcomeComponent).      |

##### `chatWelcomeComponent`

The `chatWelcomeComponent` location overlays the main chat area. When content is added to this element:

* A CSS class `has-center-chat-component` is automatically added to the document body.
* The class is removed when the element is empty.
* Use this location sparingly as it obscures the main chat interface.
* Use for loading screens, full-screen notifications, or modal-like content.

##### `aiTooltipAfterDescription`

This location appears within the AI disclaimer tooltip and has limited space. Keep content minimal and relevant to AI usage disclaimers.

## Returns

<ResponseField name="HTMLDivElement">
  Returns an `HTMLDivElement` reference that can be used to inject custom HTML content.
</ResponseField>

## Examples

The following example shows how to add a notification banner below the header:

```javascript theme={null}
const element = instance.getWriteableElement('belowHeader');
element.innerHTML = `
  <div style="padding: 12px; background-color: #0f62fe; color: white; text-align: center;">
    🔔 System maintenance scheduled for tonight at 10 PM EST
  </div>
`;
```

The following example demonstrates adding a custom image carousel above the input bar:

```javascript theme={null}
const element = instance.getWriteableElement('aboveInputBar');
element.innerHTML = `
  <div style="display: flex; gap: 8px; padding: 12px; overflow-x: auto;">
    <img src="https://example.com/image1.jpg" style="width: 100px; height: 100px; border-radius: 8px;" />
    <img src="https://example.com/image2.jpg" style="width: 100px; height: 100px; border-radius: 8px;" />
    <img src="https://example.com/image3.jpg" style="width: 100px; height: 100px; border-radius: 8px;" />
  </div>
`;
```

The following example demonstrates adding interactive buttons with click handlers:

```javascript theme={null}
const element = instance.getWriteableElement('belowWelcomeStarters');
element.innerHTML = `
  <div style="padding: 16px; text-align: center;">
    <button id="customAction1" style="padding: 8px 16px; margin: 4px; background-color: #0f62fe; color: white; border: none; border-radius: 4px; cursor: pointer;">
      View Latest Updates
    </button>
    <button id="customAction2" style="padding: 8px 16px; margin: 4px; background-color: #24a148; color: white; border: none; border-radius: 4px; cursor: pointer;">
      Contact Support
    </button>
  </div>
`;
```

The following example demonstrates adding content with scrollable overflow:

```javascript theme={null}
const element = instance.getWriteableElement('aboveWelcomeTitle');
element.innerHTML = `
  <div style="max-height: 150px; overflow-y: auto; padding: 12px; background-color: #f4f4f4; border-radius: 8px;">
    <h3 style="margin: 0 0 8px 0;">Latest Product Updates</h3>
    <ul style="margin: 0; padding-left: 20px;">
      <li>New AI-powered search feature</li>
      <li>Enhanced security protocols</li>
      <li>Improved mobile experience</li>
      <li>Integration with third-party tools</li>
      <li>Performance optimizations</li>
      <li>Bug fixes and stability improvements</li>
    </ul>
  </div>
`;
```

The following example shows how to add custom content to the AI disclaimer tooltip:

```javascript theme={null}
const element = instance.getWriteableElement('aiTooltipAfterDescription');
element.innerHTML = `
  <div style="margin-top: 12px; padding-top: 12px; border-top: 1px solid #e0e0e0; font-size: 12px;">
    <p style="margin: 0 0 8px 0; font-weight: 600;">Additional Information:</p>
    <ul style="margin: 0; padding-left: 20px; line-height: 1.5;">
      <li>AI responses are generated based on available data</li>
      <li>Always verify critical information independently</li>
      <li>For support, contact <a href="mailto:support@example.com" style="color: #0f62fe;">support@example.com</a></li>
    </ul>
  </div>
`;
```

The following example demonstrates using the center chat component for a loading screen:

```javascript theme={null}
const element = instance.getWriteableElement('chatWelcomeComponent');
element.innerHTML = `
  <div style="display: flex; flex-direction: column; align-items: center; justify-content: center; height: 100%; background-color: rgba(255, 255, 255, 0.95); padding: 24px;">
    <div style="width: 48px; height: 48px; border: 4px solid #e0e0e0; border-top-color: #0f62fe; border-radius: 50%; animation: spin 1s linear infinite;"></div>
    <p style="margin-top: 16px; font-size: 16px; color: #161616;">Loading your personalized experience...</p>
  </div>
  <style>
    @keyframes spin {
      to { transform: rotate(360deg); }
    }
  </style>
`;
```

The following example demonstrates clearing writeable element content:

```javascript theme={null}
// Clear the content
const element = instance.getWriteableElement('belowHeader');
element.innerHTML = '';
```

## Considerations

### Required CSS classes for styling

<Warning>
  To override the default chat styles, make sure your CSS selector includes the WxO container classes. For example:

  ```css theme={null}
  .WxOChatContainer.WxOChatReset.WxOChatStyles .your-class {
    <!-- Your custom content here -->
  }
  ```

  This is required because the chat implements CSS reset to prevent host page styles from affecting the chat interface.
</Warning>

### Layout support

Writeable elements are available for the following layout forms:

* Floating (`float`)
* Custom (`custom`)
* Fullscreen (`fullscreen-overlay`)

### Content size and layout

The chat does not impose specific size limits on writeable element content. However, large amounts of content might create undesirable layouts. Consider the following practices:

* Use `max-height` with `overflow: auto` for scrollable content.
* Test your content across different screen sizes.
* Avoid content that significantly increases the chat height.
* Consider using responsive design techniques.

```javascript theme={null}
// Good: Controlled height with scrolling
element.innerHTML = `
  <div style="max-height: 200px; overflow-y: auto;">
    <!-- Large content here -->
  </div>
`;
```

### Timing and initialization

<Warning>
  Do not call `getWriteableElement()` before the chat instance is initialized. The method requires an active instance and fail if called before the `onLoad` callback fires.
</Warning>

```javascript theme={null}
// CORRECT: Called after chat initialization
window.watsonxOrchestrate.onLoad = function(instance) {
  const element = instance.getWriteableElement('belowHeader');
  element.innerHTML = '<div>Content</div>';
};
```

```javascript theme={null}
// INCORRECT: Called before chat initialization
const element = wxoChat.getWriteableElement('belowHeader'); // This implementation fails

window.wxOConfiguration = {
  orchestrationID: '<tenantId>',
  chatOptions: {
    onLoad: function(instance) {
      // Instance is now available
    }
  }
};
```

<Card title="Do you need practical examples?" icon="text-align-start" href="https://www.ibm.com/docs/SSAVQO/deploy/web_chat_agent/tutorials/tutorials_lp.html" arrow="true" cta="Learn with walk-throughs" horizontal>
  Learn how to apply the features available for embedded chat into your implementation with guidance and examples.
</Card>