Checkbox field

Detailed explanation of the Checkbox field in ButterCMS, including input, output, configuration options, and use cases as a True/False toggle

The Checkbox field is a simple checkbox element that returns either True or False in the API, useful for feature flags and visibility toggles.

Field at a glance

Input and output

Input type

Checkbox element

API output

boolean

API response example

"is_featured": true,
"show_sidebar": false

Field configuration options

Checking the default value box in the field configuration options will set the field as True by default.

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

• Setting whether content should be featured or highlighted on a page
• Including content in site navigation or mobile-specific display
• Enabling comments, social sharing buttons, related posts, or newsletter forms
• Indicating whether items are in stock, on sale, new, or part of a promotion
• Showing or hiding sidebars, optional themes, dark mode, breadcrumbs

Use descriptive field names that indicate the “true” state. Names like is_featured, show_sidebar, or enable_comments make it clear what checking the box does.

Working with booleans in your application

Content like Collections and Pages can even be filtered by your Checkbox fields when queried from the API via the fields. query parameter, e.g., fields.is_featured=True

JavaScript example

const butter = require('buttercms')('your-api-key');

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

// Conditional rendering
if (post.is_featured) {
  console.log('This is a featured post!');
}

// Use in templates (React example)
function BlogPost({ post }) {
  return (
    <article className={post.is_featured ? 'featured' : ''}>
      <h1>{post.title}</h1>
      {post.show_author_bio && (
        <AuthorBio author={post.author} />
      )}
      <div>{post.content}</div>
      {post.enable_comments && (
        <CommentsSection />
      )}
    </article>
  );
}

Filtering by boolean

// Get all featured posts
const response = await butter.page.list('blog-post', {
  'fields.is_featured': true
});

// Get non-featured posts
const response = await butter.page.list('blog-post', {
  'fields.is_featured': false
});

Python example

from butter_cms import ButterCMS

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

# Boolean values are Python True/False
if post['is_featured']:
    print('This is a featured post!')

# Conditional logic
sidebar_class = 'with-sidebar' if post['show_sidebar'] else 'full-width'

Best practices

1. Use descriptive names: The field name should clearly indicate what True means
2. Set appropriate defaults: Think about what the “normal” state should be: is_featured would likely be False, include_in_shop would likely be True, etc.
3. Provide help text: Explain what happens when the checkbox is checked
4. Group related booleans: If you have many toggles, consider using components
5. Don’t overuse: Too many checkboxes can be overwhelming for editors