> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainlit.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Starters

Starters are suggestions to help your users get started with your assistant.

```python starters.py theme={null}
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",
        )
    ]
# ...
```

<Frame caption="Starters example">
  <img src="https://mintcdn.com/chainlit-43/bY2N4qUEa_bGPLfY/images/starters.gif?s=892d283700e4ca2f62166f1ba9c7a126" width="1512" height="1080" data-path="images/starters.gif" />
</Frame>

## 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`:

```python starter_categories.py theme={null}
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.

```python profile_categories.py theme={null}
@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"),
            ],
        ),
    ]
```

<Note>
  The `chat_profile` parameter is available since version **2.11.1**.
</Note>

When both `@cl.set_starters` and `@cl.set_starter_categories` are defined, categories take precedence.

<Note>
  Since version **2.10.0**.
</Note>

## With Localization

The `@cl.set_starters` callback accepts an optional `language` parameter, allowing you to return localized starters based on the user's language.

```python localized_starters.py theme={null}
@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](/advanced-features/chat-profiles). You can define different starters for different chat profiles.

```python starters_with_chat_profiles.py theme={null}
@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",
                ),
            ],
        )
    ]
```