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.

Conditional fields are fields within a Component that are shown or hidden based on the value of a trigger field (such as a checkbox or dropdown). When a conditional field is hidden in the dashboard, it is omitted entirely from the API response — your frontend only needs to handle the data that is present. For a full explanation of how to configure conditional fields in the dashboard, see Conditional Fields in Components.

​
API response example

When a conditional field is hidden in the dashboard, it will not be present in the API response. 
{
  "type": "product_card",
  "fields": {
    "product_name": "Wireless Headphones",
    "product_image": "https://cdn.buttercms.com/xxxxx",
    "regular_price": 149.99,
    "is_on_sale": true,
    "sale_price": 99.99,
    "sale_badge_text": "33% OFF",
    "sale_end_date": "2024-12-31T23:59:59Z"
  }
}

​
React Component example

const ProductCard = ({
  product_name,
  product_image,
  regular_price,
  is_on_sale,
  sale_price,
  sale_badge_text,
  sale_end_date
}) => {
  return (
    <div className="product-card">
      <div className="product-image-container">
        <img src={product_image} alt={product_name} />
        {is_on_sale && sale_badge_text && (
          <span className="sale-badge">{sale_badge_text}</span>
        )}
      </div>

      <h3>{product_name}</h3>

      <div className="pricing">
        {is_on_sale ? (
          <>
            <span className="original-price strikethrough">
              ${regular_price}
            </span>
            <span className="sale-price">${sale_price}</span>
            {sale_end_date && (
              <span className="sale-ends">
                Sale ends {new Date(sale_end_date).toLocaleDateString()}
              </span>
            )}
          </>
        ) : (
          <span className="price">${regular_price}</span>
        )}
      </div>
    </div>
  );
};

​
Frontend conditional logic

​
Conditional display by user role

const showAdminNote = user?.role === 'admin';

​
Conditional display by location

const isEU = user?.locale?.startsWith('en-') && user?.region === 'EU';

​
Conditional display by date/time

const now = new Date();
const showPromo = now >= new Date(promo.start) && now <= new Date(promo.end);

​
Conditional display by device

const isMobile =
  typeof window !== 'undefined' &&
  window.matchMedia('(max-width: 768px)').matches;

​
Building a visibility Component

​
Visibility control schema

Use a small component to centralize visibility rules: 
{
  "type": "visibility_rule",
  "fields": {
    "audience": "admins",
    "start_date": "2024-12-01",
    "end_date": "2024-12-31"
  }
}

​
Frontend implementation

const isVisible = ({ audience, start_date, end_date }, user) => {
  const now = new Date();
  if (start_date && now < new Date(start_date)) return false;
  if (end_date && now > new Date(end_date)) return false;
  if (audience === 'admins' && user?.role !== 'admin') return false;
  return true;
};

​
Best practices

​
Performance

  1. Avoid deeply nested conditional trees in your UI.
  2. Cache content responses when rules do not change often.

​
Analytics

  1. Track which variants are shown to users.
  2. Log conditional decisions to debug content issues.