Skip to main content
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 NameTypeFunction
Required?booleanMake field required to save page
Help textstringAdd help text to describe usage to your team
Default valuestringSet 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.

​
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)
The number of options you need to include can help you decide on what field type to use.
Option countRecommendation
2Consider using checkbox(es) instead
3-10Ideal for dropdown
10+Consider using a Reference to a Collection
Use Dropdown whenUse Reference when
Options are static/rarely changeOptions change frequently
Simple value selectionOptions need additional data (icon, description)
Developer-controlled optionsEditor-controlled options
Less than ~10 optionsMany options
No additional metadata neededOptions 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