[](https://vaadin.com/directory/component/chat-assistant-add-on)
[](https://vaadin.com/directory/component/chat-assistant-add-on)
[](https://jenkins.flowingcode.com/job/ChatAssistant-addon)
[](https://mvnrepository.com/artifact/org.vaadin.addons.flowingcode/chat-assistant-addon)
[](https://javadoc.flowingcode.com/artifact/org.vaadin.addons.flowingcode/chat-assistant-addon)
# Chat Assistant Add-on
Vaadin Add-on that displays a chat assistant floating window using [Material UI's FAB](https://mui.com/material-ui/react-floating-action-button/) and Vaadin web components.
## Features
* Send messages from the user or programmatically, and listen for messages written by the user.
* Toggle the chat window open/closed, or open it as a full-screen dialog on mobile.
* Markdown rendering, lazy loading via a `DataProvider`, and streaming ("generative") answers.
* Customizable floating action button (FAB): icon, size, color (`FabVariant` theme variants),
corner position and margin, draggable or fixed, and viewport- or container-anchored placement.
* Resizable chat window with eight drag handles, optional resize direction indicators, and
configurable initial size with min/max bounds.
* Responsive desktop/mobile modes with optional breakpoint-based auto-switching, plus listeners for
mode changes and for the chat window crossing a size threshold.
* A fluent `ChatAssistant.builder()` to configure everything declaratively.
## Supported versions
Supported versions: Vaadin 24-25 (add-on version 4.x)
## Online demo
[Online demo here](http://addonsv24.flowingcode.com/chat-assistant)
## Download release
[Available in Vaadin Directory](https://vaadin.com/directory/component/chat-assistant)
### Maven install
Add the following dependencies in your pom.xml file:
```xml
org.vaadin.addons.flowingcode
chat-assistant-addon
X.Y.Z
```
Release versions since 5.0.1 are available from Maven Central repository. Earlier versions are available from the Vaadin add-on repository. For SNAPSHOT versions see [here](https://maven.flowingcode.com/snapshots/).
## Building and running demo
- git clone repository
- mvn clean install jetty:run
To see the demo, navigate to http://localhost:8080/
## Release notes
See [here](https://github.com/FlowingCode/ChatAssistant/releases)
## Issue tracking
The issues for this add-on are tracked on its github.com page. All bug reports and feature requests are appreciated.
## Contributions
Contributions are welcome. There are two primary ways you can contribute: by reporting issues or by submitting code changes through pull requests. To ensure a smooth and effective process for everyone, please follow the guidelines below for the type of contribution you are making.
#### 1. Reporting Bugs and Requesting Features
Creating an issue is a highly valuable contribution. If you've found a bug or have an idea for a new feature, this is the place to start.
* Before creating an issue, please check the existing issues to see if your topic is already being discussed.
* If not, create a new issue, choosing the right option: "Bug Report" or "Feature Request". Try to keep the scope minimal but as detailed as possible.
> **A Note on Bug Reports**
>
> Please complete all the requested fields to the best of your ability. Each piece of information, like the environment versions and a clear description, helps us understand the context of the issue.
>
> While all details are important, the **[minimal, reproducible example](https://stackoverflow.com/help/minimal-reproducible-example)** is the most critical part of your report. It's essential because it removes ambiguity and allows our team to observe the problem firsthand, exactly as you are experiencing it.
#### 2. Contributing Code via Pull Requests
As a first step, please refer to our [Development Conventions](https://github.com/FlowingCode/DevelopmentConventions) page to find information about Conventional Commits & Code Style requirements.
Then, follow these steps for creating a contribution:
- Fork this project.
- Create an issue to this project about the contribution (bug or feature) if there is no such issue about it already. Try to keep the scope minimal.
- Develop and test the fix or functionality carefully. Only include minimum amount of code needed to fix the issue.
- For commit message, use [Conventional Commits](https://github.com/FlowingCode/DevelopmentConventions/blob/main/conventional-commits.md) to describe your change.
- Send a pull request for the original project.
- Comment on the original issue that you have implemented a fix for it.
## License & Author
This add-on is distributed under Apache License 2.0. For license terms, see LICENSE.txt.
Chat Assistant Add-on is written by Flowing Code S.A.
# Developer Guide
## Getting started
`ChatAssistant` renders a floating action button (FAB) that opens a chat window.
Add it to any layout and send messages to it; it shows a FAB in the bottom-right corner by default.
```java
ChatAssistant chatAssistant = new ChatAssistant<>();
add(chatAssistant);
// Send a message programmatically (e.g. from the assistant).
chatAssistant.sendMessage(Message.builder()
.name("Assistant")
.content("Hello, I am here to assist you")
.messageTime(LocalDateTime.now())
.build());
// React to messages typed by the user.
chatAssistant.setSubmitListener(ev ->
chatAssistant.sendMessage(Message.builder()
.name("User")
.content(ev.getValue())
.messageTime(LocalDateTime.now())
.build()));
// Open or close the window programmatically.
chatAssistant.setOpened(true);
```
### Configuring with the builder
Use `ChatAssistant.builder()` to configure the FAB and window declaratively:
```java
ChatAssistant chatAssistant = ChatAssistant.builder()
.fabIcon(new SvgIcon("icons/my-icon.svg")) // custom FAB icon (defaults to a chatbot icon)
.defaultFabPosition(FabPosition.BOTTOM_LEFT)
.fabMovable(true) // allow dragging the FAB
.resizable(true) // allow resizing the window
.markdownEnabled(true) // render message content as Markdown
.build();
```
Everything in the builder also has a setter, so the FAB and window can be reconfigured at runtime.
### Styling the FAB
```java
chatAssistant.setFabPosition(FabPosition.TOP_RIGHT); // move it (and set the reset corner)
chatAssistant.addFabThemeVariants(FabVariant.LARGE); // grow the FAB (FabVariant.SMALL/LARGE)
chatAssistant.addFabThemeVariants(FabVariant.LUMO_CONTRAST); // recolor it (color variants)
chatAssistant.setResizeIndicatorsVisible(true); // show resize-direction hints
```
### Sizing the window
```java
chatAssistant.setWindowWidth("400px");
chatAssistant.setWindowHeight("500px");
chatAssistant.setWindowMinWidth(300); // bounds honored on open and while resizing
chatAssistant.setWindowMaxWidth(700);
```
### Responsive / mobile mode
In `MOBILE` mode the chat opens as a full-screen dialog. Set a breakpoint to switch automatically
between desktop (anchored popover) and mobile as the viewport crosses it:
```java
ChatAssistant chatAssistant = ChatAssistant.builder()
.mobileBreakpoint(768) // auto-switch to mobile below 768px (auto-switching is opt-in)
.build();
chatAssistant.addModeChangedListener(ev -> Notification.show("Now in " + ev.getMode() + " mode"));
chatAssistant.setMode(ChatAssistantMode.MOBILE); // or switch manually
```
## Special configuration when using Spring
By default, Vaadin Flow only includes ```com/vaadin/flow/component``` to be always scanned for UI components and views. For this reason, the add-on might need to be allowed in order to display correctly.
To do so, just add ```com.flowingcode``` to the ```vaadin.allowed-packages``` property in ```src/main/resources/application.properties```, like:
```
vaadin.allowed-packages = com.vaadin,org.vaadin,dev.hilla,com.flowingcode
```
More information on Spring scanning configuration [here](https://vaadin.com/docs/latest/integrations/spring/configuration/#configure-the-scanning-of-packages).