Skip to main content
Starters are suggestions to help your users get started with your assistant.
starters.py
import chainlit as cl

@cl.set_starters
async def set_starters():
    return [
        cl.Starter(
            label="Morning routine ideation",
            message="Can you help me create a personalized morning routine that would help increase my productivity throughout the day? Start by asking me about my current habits and what activities energize me in the morning.",
            icon="/public/idea.svg",
        ),

        cl.Starter(
            label="Explain superconductors",
            message="Explain superconductors like I'm five years old.",
            icon="/public/learn.svg",
        ),
        cl.Starter(
            label="Python script for daily email reports",
            message="Write a script to automate sending daily email reports in Python, and walk me through how I would set it up.",
            icon="/public/terminal.svg",
            command="code",
        ),
        cl.Starter(
            label="Text inviting friend to wedding",
            message="Write a text asking a friend to be my plus-one at a wedding next month. I want to keep it super short and casual, and offer an out.",
            icon="/public/write.svg",
        )
    ]
# ...

​
Starter Categories

You can group starters into categories that appear as clickable buttons. Users select a category to reveal its starters. Define categories with @cl.set_starter_categories:
starter_categories.py
import chainlit as cl

@cl.set_starter_categories
async def starter_categories(user: cl.User):
    return [
        cl.StarterCategory(
            label="Creative",
            icon="https://example.com/creative.png",  # optional
            starters=[
                cl.Starter(label="Write a poem", message="Write a poem about the sea"),
                cl.Starter(label="Write a story", message="Write a short story"),
            ],
        ),
        cl.StarterCategory(
            label="Educational",
            starters=[
                cl.Starter(label="Explain", message="Explain quantum computing"),
            ],
        ),
    ]
StarterCategory accepts:
  • label (str) — the category button text
  • icon (str, optional) — URL for the category icon
  • starters (List[Starter]) — starters shown when the category is selected
The callback accepts the same optional parameters as @cl.set_starters: user, language, and chat_profile. All are optional — declare only what you need.
profile_categories.py
@cl.set_starter_categories
async def starter_categories(user: cl.User, language: str, chat_profile: str):
    if chat_profile == "Advanced":
        return [
            cl.StarterCategory(
                label="Advanced",
                starters=[
                    cl.Starter(label="Deep dive", message="Explain in detail"),
                ],
            ),
        ]
    return [
        cl.StarterCategory(
            label="General",
            starters=[
                cl.Starter(label="Hello", message="Say hello"),
            ],
        ),
    ]
The chat_profile parameter is available since version 2.11.1.
When both @cl.set_starters and @cl.set_starter_categories are defined, categories take precedence.
Since version 2.10.0.

​
With Localization

The @cl.set_starters callback accepts an optional language parameter, allowing you to return localized starters based on the user’s language.
localized_starters.py
@cl.set_starters
async def set_starters(current_user: cl.User, language: str):
    if language == "fr":
        return [
            cl.Starter(
                label="Routine matinale",
                message="Pouvez-vous m'aider à créer une routine matinale personnalisée ?",
                icon="/public/idea.svg",
            ),
        ]
    return [
        cl.Starter(
            label="Morning routine ideation",
            message="Can you help me create a personalized morning routine?",
            icon="/public/idea.svg",
        ),
    ]

​
With Chat Profiles

Starters also work with Chat Profiles. You can define different starters for different chat profiles.
starters_with_chat_profiles.py
@cl.set_chat_profiles
async def chat_profile(current_user: cl.User):
    if current_user.metadata["role"] != "ADMIN":
        return None

    return [
        cl.ChatProfile(
            name="My Chat Profile",
            icon="https://picsum.photos/250",
            markdown_description="The underlying LLM model is **GPT-3.5**, a *175B parameter model* trained on 410GB of text data.",
            starters=[
                cl.Starter(
                    label="Morning routine ideation",
                    message="Can you help me create a personalized morning routine that would help increase my productivity throughout the day? Start by asking me about my current habits and what activities energize me in the morning.",
                    icon="/public/idea.svg",
                ),
                cl.Starter(
                    label="Explain superconductors",
                    message="Explain superconductors like I'm five years old.",
                    icon="/public/learn.svg",
                ),
            ],
        )
    ]