Like what we’re doing? Star us on GitHub!

What's the difference between blocks and relationships?

8 months ago
1 2

Hi payload dev dudes,

I'm migrating our 50k+ pages SEO web app from Contentful to Payload. I found blocks and relationships to collections(in rich-text editor) both can solve the requirement of inserting structured data into an article.

We're now using contentful embed block(like relationship) to do this. And the embedded block links to contents(like doc) built from content types(like collections). For example we have pure UI content types like Button, Card and TwitterWidget, also we have business-related content types like TableRealStatisticsForCalifornia.

I'd like to know from the best practice aspect, when should I use blocks and when should I use relationships to collections.

  • jmikrut
    Payload Team
    8 months ago

    Hey @Stupidism — great question and AWESOME to hear that you are moving from Contentful to Payload.

    So, when I first started using Contentful, I was a bit surprised by the fact that their solution to "flexible content" was simply by building a list of relations to other content models. This meant that I needed to have a content model for every single different "block" and that can get unwieldy very quickly. For trivial blocks, like a "content" block (which is extremely unlikely to be reused), you still have to make another content model and then just define a relationship.

    Payload does things in a much more flexible way, which leaves it up to you to determine if you should use a block or a relationship field.

    Payload's blocks are great because the data is stored directly on the top-level document which is great for performance and makes sense from a data model for a lot of cases. If your block's data is a one-off, you should use blocks with specific fields and store the data right on the top-level document.

    But, if you wanted to re-use a block's data from page to page, or similar, you still can. In that case, you would build a block that contains a relationship field to another collection, and then just reference the document that you want within the block.

    For example, in our public demo we have a block called Embedded Form. This block contains a relationship field to a forms collection, which lets admins place forms directly within their layout builder but the form itself can be reused across many pages.


    Basically, the rule of thumb for us is that whenever we can, we use blocks and store data directly on the top-level document. But, if the data within a block needs to be reused or should be global, then we would use a relationship field within a block to point to another document.

    Does that make sense?

    1 reply
  • Stupidism
    8 months ago

    Yes, I had a similar thought like yours. Thanks~~~

  • Stupidism
    8 months ago

    Just to expand the questions a little bit. Is it possible to insert blocks inside the richtext directly(not with a relationship, and also not break the whole article apart into several blocks)? @jmikrut

    2 replies
    Payload Team
    8 months ago

    Yes, it is. The richText field has a relationship element, that allows you to dynamically reference other documents directly within any rich text field.

    Here are the docs for that:

    8 months ago

    In that way, it's a relationship again. I was trying to know if we can do without relationship.

Open the post
Continue the discussion in GitHub
Can't find what you're looking for?
Get help straight from the Payload team with an Enterprise License.Learn More