Working with Groups

Groups in BCMS are reusable building blocks made up of multiple properties. They help you organize and nest structured content in Templates and Widgets.

A group is like a mini-template: defined once and reused anywhere. You can use groups:

  • Inside templates

  • Inside widgets

  • Inside other groups (nested groups)

This makes groups powerful for representing repeating or nested content structures, such as FAQs, social links, testimonials, or sections with shared structure.


Creating and Editing a Group

To create a group in the BCMS dashboard:

  1. Navigate to Groups in the sidebar.

  2. Click Create New Group.

  3. Set a label and optional description.

  4. Add properties by dragging field types into the group builder.

main.jpg

To edit a group:

  • Click on the group name to open it.

  • Use Edit Group to rename or update the description.

  • Modify its properties directly in the builder interface.


Adding Properties to a Group

You can add any supported BCMS field type to a group, including:

  • String

  • Media

  • Rich text

  • Boolean

  • Number

  • Date

  • Entry pointer

  • Other groups (for nesting)

Each property becomes part of the reusable group definition and can be type-safe in code thanks to BCMS’s automatic type generation.


Groups in Templates, Widgets, and Other Groups

Groups can be used almost anywhere:

  • In templates: Add a group field to create a shared block of properties used in every entry.

  • In widgets: For modular content blocks that need structured fields.

  • In other groups: To create nested, reusable patterns of data.

You can also make a group repeatable (an array), which is useful for:

  • Testimonials

  • Steps in a guide

  • Features or pricing tiers

  • FAQs


Type-safe usage in code

BCMS generates TypeScript types for every group you define. You can import and use these types for full type safety when rendering entries:

import type { TestimonialGroup } from '@bcms-types/ts';

type Props = {
  data: TestimonialGroup[];
};

export const Testimonials = ({ data }: Props) => (
  <section>
    {data.map((testimonial) => (
      <blockquote key={testimonial.quote}>
        <p>{testimonial.quote}</p>
        <footer>{testimonial.name}</footer>
      </blockquote>
    ))}
  </section>
);

Example: Group inside a template

Imagine you have a Team Member template, and you want each member to have multiple social links. You can create a SocialLink group with properties like platform, url, and icon.

Then add the group to your template as a repeatable field.

import { bcms } from '@/bcms';
import type { TeamMemberEntryMetaItem } from '@bcms-types/ts';

const entry = await bcms.entry.getById<TeamMemberEntryMetaItem>(
  'team-member-slug',
  'team-member'
);

entry.meta.social_links.forEach((link) => {
  console.log(link.platform, link.url);
});

Finding where a Group is used

To programmatically find out where a group is used, call:

const usage = await bcms.group.whereIsItUsed('group_id');

console.log(usage);
// Output: list of templates, widgets, and groups where this group is referenced

This is helpful for impact analysis before deleting or updating a group.


Fetching Groups via SDK

You can retrieve group definitions directly in your code using the @thebcms/client:

// Get all groups
const groups = await bcms.group.getAll();

// Get one group by ID
const group = await bcms.group.getById('group_id');

The SDK uses in-memory caching for performance. Use skipCache: true to force-refresh data.

Deleting a Group

To delete a group:

  1. Open the group from the Groups section.

  2. Click Edit Group.

  3. Click Delete Group.

⚠️ Deleting a group will remove it from any template, widget, or group that uses it. Check where it's used before deleting, especially in production.


Conclusion

Groups are a core part of creating structured, maintainable, and scalable content models in BCMS.

Use them to:

  • Define reusable, structured patterns of fields

  • Organize complex templates

  • Avoid duplication

  • Render type-safe components in your frontend

Combined with BCMS's automatic type generation and content parsing utilities, groups make content modeling clean and developer-friendly.