Rendering Conditional Fields

Implement frontend logic to render conditional fields from ButterCMS Components.

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.