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.

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.

Field at a glance

Input and output

Input type

Dropdown (select menu)

API output

string (from set of predefined choices)

API response example

"status": "waiting-on-review"

Field configuration options

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.

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

{
  "article_attributes_field": {
    "status": "published",
    "category": "tutorial",
    "difficulty_level": "beginner"
  }
}

{
  "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.

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).

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.

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):

{
  "category": "tutorial"
}

Reference approach (dynamic categories with metadata):

{
  "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

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

// 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

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

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