---
updatedAt: 2025-12-10T17:23:23.000Z
agentTools:
projectIndex: https://developers.alby.com/llms.txt
---
# alby-questionnaire
Help customers find the right products by presenting a series of questions that narrow down products within a category.
## Prerequisites
* Ensure alby is installed to unlock these elements and elevate your storefront. Learn more [here](https://developers.alby.com/docs/installing-alby).
***
## Usage
The `alby-questionnaire` component offers two behavior modes that can be selected from the admin panel.
It can be embedded into your webpage in two different ways, as illustrated in the examples below.
### Dynamic Questionnaire
The dynamic questionnaire uses AI to generate the questions based on the category and sample product ids.
#### Basic Example
```html
```
### Properties
| Attribute | Description | Type | Default | Required |
| :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------- | :---------- | :------- |
| `widget-id` | The unique identifier for the widget, found on the Widget Embed page in the alby Dashboard. Required for correctly loading the designated widget instance. | `string` | `undefined` | Yes |
| `category` | The product category for contextual AI responses. | `boolean` | `undefined` | Yes |
| `product-ids` | Comma-separated list of external product IDs for multi-product contexts. | `string` | `undefined` | Yes |
| `test-mode` | Enables internal testing of the widget. When enabled, conversations created will not appear in the inbox or impact reporting. **This is not related to A/B testing.** | `boolean` | `undefined` | No |
### Custom Questionnaire
The custom questionnaire uses a set of pre-defined static questions to generate the questionnaire.
#### Basic Example
```html
```
### Properties
| Attribute | Description | Type | Default | Required |
| :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------- | :---------- | :------- |
| `widget-id` | The unique identifier for the widget, found on the Widget Embed page in the alby Dashboard. Required for correctly loading the designated widget instance. | `string` | `undefined` | Yes |
| `test-mode` | Enables internal testing of the widget. When enabled, conversations created will not appear in the inbox or impact reporting. **This is not related to A/B testing.** | `boolean` | `undefined` | No |
***
## CSS Variables Configuration
The `alby-guided-questionnaire` component can be customized using CSS custom properties (CSS variables). These variables allow you to control the appearance and behavior of the guided questionnaire without modifying the component's internal styles.
### Usage
You can set these variables using inline styles on the component:
```html
```
### Priority Order
CSS variables follow this priority order (highest to lowest):
1. **Inline styles** - Set directly on the component element
2. **Widget styling** - Configured through the Alby dashboard
3. **Default values** - Built-in component defaults
### Available CSS Variables
| CSS Variable | Description | Default Value |
| ------------------------------------------- | --------------------------------------------------------------------------------- | --------------------- |
| `--alby-questionnaire-max-height` | Sets the maximum height of the questionnaire container on both desktop and mobile | `500px` |
| `--alby-questionnaire-max-width-desktop` | Sets the maximum width of the questionnaire container on desktop | `640px` |
| `--alby-questionnaire-max-width-mobile` | Sets the maximum width of the questionnaire container on mobile | `100%` |
| `--alby-questionnaire-container-padding` | Sets the padding of the questionnaire container | `24px` |
| `--alby-questionnaire-background` | Sets the background color of the questionnaire container | `#ffffff` |
| `--alby-questionnaire-border-width` | Sets the border width of the questionnaire container | `1px` |
| `--alby-questionnaire-border-color` | Sets the border color of the questionnaire container | `#f3f4f6` |
| `--alby-questionnaire-border-radius` | Sets the border radius of the questionnaire container | `16px` |
| `--alby-questionnaire-font-size` | Sets the font size of the question text | `18px` |
| `--alby-questionnaire-question-font-weight` | Sets the font weight of the question text | `500` |
| `--alby-questionnaire-question-color` | Sets the text color of the question | `#111827` |
| `--alby-questionnaire-button-font-size` | Sets the font size of the option buttons | `14px` |
| `--alby-questionnaire-button-padding` | Sets the padding of the option buttons | `8px 16px` |
| `--alby-questionnaire-button-background` | Sets the background color of the option buttons | `#F0F2F7` |
| `--alby-questionnaire-button-color` | Sets the text color of the option buttons | `#1F2A37` |
| `--alby-questionnaire-button-border` | Sets the border of the option buttons | `none` |
| `--alby-questionnaire-button-border-radius` | Sets the border radius of the option buttons | `9999px` |
| `--alby-questionnaire-icon-display` | Sets the display property of the AI logo icon | `block` |
| `--alby-questionnaire-icon-size` | Sets the size of the AI logo icon | `18px` |
| `--alby-questionnaire-icon-color` | Sets the color of the AI logo icon | `#111928` |
| `--alby-questionnaire-font-family` | Sets the font family for the entire component | `Figtree, sans-serif` |
### Notes
* The component automatically applies responsive behavior for mobile devices using the `--alby-questionnaire-max-width-mobile` variable
* **Responsive Breakpoint**: The component uses `@media (max-width: 768px)` as the breakpoint to switch between desktop and mobile layouts