Skip to main content

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.

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

  • 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