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

# 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

<CardGroup cols={2}>
  <Card title="Input type" icon="arrow-right-to-bracket">
    Checkbox element
  </Card>

  <Card title="API output" icon="arrow-right-from-bracket">
    `boolean`
  </Card>
</CardGroup>

### API response example

```json theme={null}
"is_featured": true,
"show_sidebar": false
```

### Field configuration options

<Tip>
  Checking the `default value` box in the field configuration options will set the field as `True` by default.
</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

* 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

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

## Working with booleans in your application

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

### JavaScript example

```javascript theme={null}
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

```javascript theme={null}
// 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

```python theme={null}
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