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

# Dropdown field

> Detailed explanation of the Dropdown field in ButterCMS, including input, output, configuration options, and use cases as select field for predefined choices

The **Dropdown** field provides a way for content editors to select from a list of choices that you predefine when setting up a content schema.

<Tip>
  For color selection, we recommend using the Color field instead, but there are cases where you might want to use the Dropdown field—like limiting content creators to a short list of static options.
</Tip>

## Field at a glance

### Input and output

<CardGroup cols={2}>
  <Card title="Input type" icon="arrow-right-to-bracket">
    Dropdown (select menu)
  </Card>

  <Card title="API output" icon="arrow-right-from-bracket">
    `string` (from set of predefined choices)
  </Card>
</CardGroup>

### API response example

```json theme={null}
"status": "waiting-on-review"
```

### Field configuration options

<Tip>
  When setting up your field, each option will have a Label, indicating what the editor sees, and a Value, indicating what is returned via the API. We recommend using kebab-case for the Value, which keeps them human readable.
</Tip>

| `Option Name` | `Type`  | `Function`                                   |
| ------------- | ------- | -------------------------------------------- |
| Required?     | boolean | Make field required to save page             |
| Help text     | string  | Add help text to describe usage to your team |
| Default value | string  | Set a default value for the field            |

## Common use cases

* Tracking content status: `draft`, `review`, `published`, `archived`
* Options to categorize content types: `blog`, `tutorial`, `case-study`, `news`, `announcement`
* Difficulty level to indicate skill level: `beginner`, `intermediate`, `advanced`, `expert`
* Indicate task or content priority and importance: `low`, `medium`, `high`, `critical`
* Page layout options or template selection: `default`, `sidebar-left`, `sidebar-right`, `full-width`
* Product attributes: `xs`, `small`, `medium`, `red`, `blue`, `black`, `bonus`

```json theme={null}
{
  "article_attributes_field": {
    "status": "published",
    "category": "tutorial",
    "difficulty_level": "beginner"
  }
}
```

```json theme={null}
{
  "t_shirt_options": {
    "size": "medium",
    "color": "navy-blue",
    "material": "cotton",
    "availability": "in-stock"
  }
}
```

# Adding options: slugs and choices

When you add an option to the field to be selected, it has two parts:

* **Choice**: What the editor sees in the dropdown
* **Slug**: What gets stored and returned via API

Slugs are automatically populated in the dashboard for each choice you add.

```text theme={null}
Choice: "In Stock"
Slug: "in-stock"

Choice: "Out of Stock"
Slug: "out-of-stock"

Choice: "Pre-Order"
Slug: "pre-order"
```

If you don't like the automatically-created slug, you can edit it, but the dashboard will then slugify your edits so that they can be properly saved and returned by our API. Any uppercase characters will be converted to lowercase, special characters like `*` are removed, and spaces are converted to hyphens `-` (kebab-case).

<Tip>
  Underscores (snake\_case) *are* allowed, but recommend sticking with hyphens (kebab-case), as it's easy for your development team to work with, human-readable, and will be consistent with any auto-populated slugs.
</Tip>

## Dropdowns best practices

### General principles

1. **Keep options concise**: Short, clear labels work best
2. **Set sensible defaults**: The default should be the most common choice
3. **Add help text**: Explain what each option means if not obvious
4. **Consider future needs**: Will you need to add more options later?
5. **Document option meanings**: Keep a reference of what each value means for your team

#### Ordering options

Consider how options should be ordered:

1. **Alphabetical**: When options are equivalent (colors, categories)
2. **Sequential**: When there's a progression (beginner → advanced)
3. **Frequency**: Most common first (default, standard, then special cases)
4. **Workflow**: Following a process (draft → review → published)

## Dropdowns vs. other field types

The number of options you need to include can help you decide on what field type to use.

| Option count | Recommendation                             |
| ------------ | ------------------------------------------ |
| 2            | Consider using checkbox(es) instead        |
| 3-10         | Ideal for dropdown                         |
| 10+          | Consider using a Reference to a Collection |

| Use Dropdown when                | Use Reference when                               |
| -------------------------------- | ------------------------------------------------ |
| Options are static/rarely change | Options change frequently                        |
| Simple value selection           | Options need additional data (icon, description) |
| Developer-controlled options     | Editor-controlled options                        |
| Less than \~10 options           | Many options                                     |
| No additional metadata needed    | Options have related fields                      |

### Example of additional metadata: categories

**Dropdown approach** (static categories):

```json theme={null}
{
  "category": "tutorial"
}
```

**Reference approach** (dynamic categories with metadata):

```json theme={null}
{
  "category": {
    "name": "Tutorial",
    "slug": "tutorial",
    "icon": "https://cdn.buttercms.com/icon.png",
    "description": "Step-by-step guides"
  }
}
```

## Working with dropdowns in your application

### JavaScript example

```javascript theme={null}
const butter = require('buttercms')('your-api-key');

const response = await butter.page.retrieve('*', 'article-page');
const article = response.data.data.fields;

// Use the dropdown value
const status = article.status; // "published"
const category = article.category; // "tutorial"

// Conditional rendering based on dropdown
function ArticleBadge({ category }) {
  const badges = {
    'tutorial': { label: 'Tutorial', color: 'blue' },
    'case-study': { label: 'Case Study', color: 'green' },
    'news': { label: 'News', color: 'orange' },
    'announcement': { label: 'Announcement', color: 'purple' }
  };

  const badge = badges[category] || { label: category, color: 'gray' };
  return <span className={`badge-${badge.color}`}>{badge.label}</span>;
}

// Switch statement for dropdown values
function getLayoutClass(layout) {
  switch (layout) {
    case 'full-width':
      return 'layout-full';
    case 'sidebar-left':
      return 'layout-sidebar-left';
    case 'sidebar-right':
      return 'layout-sidebar-right';
    default:
      return 'layout-default';
  }
}
```

### Filtering by dropdown value

```javascript theme={null}
// Get all published articles
const response = await butter.page.list('article', {
  'fields.status': 'published'
});

// Get tutorials only
const tutorials = await butter.page.list('article', {
  'fields.category': 'tutorial'
});
```

### Python example

```python theme={null}
from butter_cms import ButterCMS

client = ButterCMS('your-api-key')
response = client.pages.get('*', 'article-page')
article = response['data']['fields']

# Access dropdown value
status = article['status']  # "published"
category = article['category']  # "tutorial"

# Map to display values
CATEGORY_LABELS = {
    'tutorial': 'Tutorial',
    'case-study': 'Case Study',
    'news': 'News',
    'announcement': 'Announcement'
}

display_category = CATEGORY_LABELS.get(category, category.title())
```

### Example: status field configuration

```text theme={null}
Field Name: status
Help Text: "Select the publication status for this content"
Options:
  - Label: "Draft", Value: "draft"
  - Label: "In Review", Value: "review"
  - Label: "Published", Value: "published"
  - Label: "Archived", Value: "archived"
Default: "draft"
Required: Yes
```