How to Add Rounded Section Backgrounds to a UICollectionView Using JJCollectionViewRoundFlowLayout

JJCollectionViewRoundFlowLayout is a drop-in replacement for UICollectionViewFlowLayout that automatically draws customizable decorative views behind each section, enabling rounded corners, background colors, shadows, and borders without manual view hierarchy manipulation.

Adding distinct visual grouping to UICollectionView sections typically requires complex custom layout calculations or manual decoration view management. The open-source library kingjiajie/jjcollectionviewroundflowlayout simplifies this by extending UICollectionViewFlowLayout to render rounded backgrounds behind each section through a delegate-driven configuration model. This guide explains how to add rounded section backgrounds to your UICollectionView using the library's delegate protocol and JJCollectionViewRoundConfigModel.

How JJCollectionViewRoundFlowLayout Works

JJCollectionViewRoundFlowLayout inherits from UICollectionViewFlowLayout and registers a custom decoration view of kind JJCollectionViewRoundSection (implemented as JJCollectionReusableView) for each section. When the layout's isRoundEnabled property is set to YES (the default), the layout queries its delegate for a configuration model that defines the visual appearance of the section background.

The layout calculates the frame for each section's decorative background based on the cell positions, then applies the styling attributes you provide through the delegate protocol. This approach keeps your view controller code clean while providing per-section customization capabilities.

Implementing the Delegate Protocol

To add rounded section backgrounds, your view controller must conform to JJCollectionViewDelegateRoundFlowLayout and implement the required configuration method. The protocol defines two primary delegate methods for controlling background appearance and spacing.

Required: Providing the Configuration Model

The core method returns a JJCollectionViewRoundConfigModel that specifies the background's visual properties:

- (JJCollectionViewRoundConfigModel *)collectionView:(UICollectionView *)collectionView
                                             layout:(UICollectionViewLayout *)collectionViewLayout
                         configModelForSectionAtIndex:(NSInteger)section;

In JJCollectionViewRoundConfigModel.h, the model exposes properties for customizing the background:

• backgroundColor – The fill color of the section background
• cornerRadius – The radius of rounded corners (default is 0)
• maskedCorners – Specific corners to round (iOS 11+)
• borderWidth and borderColor – Optional stroke around the background
• shadowColor, shadowOffset, shadowOpacity, shadowRadius – Drop shadow parameters
• bgImage – An optional image to draw instead of a solid color

Optional: Adjusting Background Insets

To control the spacing between the background decoration and the section's cells, implement the optional border insets method:

- (UIEdgeInsets)collectionView:(UICollectionView *)collectionView
                       layout:(UICollectionViewLayout *)collectionViewLayout
       borderEdgeInsertsForSectionAtIndex:(NSInteger)section;

This method returns UIEdgeInsets that apply specifically to the decorative background view, separate from the collection view's sectionInset, creating padding inside the rounded background rectangle.

Step-by-Step Implementation

Follow these steps to integrate rounded section backgrounds into your existing UICollectionView implementation.

1. Configure the Layout

Replace your standard flow layout with JJCollectionViewRoundFlowLayout and assign your view controller as the delegate:

#import "JJCollectionViewRoundFlowLayout.h"

JJCollectionViewRoundFlowLayout *layout = [[JJCollectionViewRoundFlowLayout alloc] init];
layout.delegate = self;
layout.scrollDirection = UICollectionViewScrollDirectionVertical;
layout.isRoundEnabled = YES; // Enabled by default, but explicit for clarity

self.collectionView.collectionViewLayout = layout;

2. Implement the Configuration Delegate

Conform your view controller to JJCollectionViewDelegateRoundFlowLayout and provide the background configuration:

#pragma mark - JJCollectionViewDelegateRoundFlowLayout

- (UIEdgeInsets)collectionView:(UICollectionView *)collectionView
                       layout:(UICollectionViewLayout *)collectionViewLayout
       borderEdgeInsertsForSectionAtIndex:(NSInteger)section {
    // 5 pt vertical padding, 12 pt horizontal padding
    return UIEdgeInsetsMake(5.f, 12.f, 5.f, 12.f);
}

- (JJCollectionViewRoundConfigModel *)collectionView:(UICollectionView *)collectionView
                                             layout:(UICollectionViewLayout *)collectionViewLayout
                         configModelForSectionAtIndex:(NSInteger)section {
    
    JJCollectionViewRoundConfigModel *model = [[JJCollectionViewRoundConfigModel alloc] init];
    
    // Light gray background
    model.backgroundColor = [UIColor colorWithRed:233/255.0 
                                           green:233/255.0 
                                            blue:233/255.0 
                                           alpha:1.0];
    
    // 10 pt corner radius for all corners
    model.cornerRadius = 10.0;
    
    // Optional border styling
    // model.borderWidth = 1.0;
    // model.borderColor = [UIColor lightGrayColor];
    
    // Optional shadow
    // model.shadowColor = [UIColor blackColor];
    // model.shadowOffset = CGSizeMake(0, 2);
    // model.shadowOpacity = 0.2;
    // model.shadowRadius = 4.0;
    
    return model;
}

The code above creates a light gray rounded rectangle with 10-point corners and internal padding of 5 points top/bottom and 12 points left/right, matching the visual presentation in the repository's example screenshots stored in Example/JJCollectionViewRoundFlowLayout/ThirdViewController.m.

Adding Touch Animations

For interactive feedback, the library supports tap animations on the section backgrounds. Implement these optional delegate methods to enable scaling animations when users touch a section background.

Enable animations for specific sections:

- (BOOL)collectionView:(UICollectionView *)collectionView
                layout:(UICollectionViewLayout *)collectionViewLayout
isDecorationViewShowAnimationAtIndex:(NSInteger)section {
    return (section == 2); // Only animate section 2
}

Customize the animation parameters:

- (JJCollectionViewTouchAnimationConfigModel *)collectionView:(UICollectionView *)collectionView
                                                      layout:(UICollectionViewLayout *)collectionViewLayout
                                 animationConfigModelForSection:(NSInteger)section {
    JJCollectionViewTouchAnimationConfigModel *anim = [[JJCollectionViewTouchAnimationConfigModel alloc] init];
    anim.duration = 0.15;
    anim.scale = 0.95;
    return anim;
}

Key Source Files

The implementation spans several files in the kingjiajie/jjcollectionviewroundflowlayout repository:

• JJCollectionViewRoundFlowLayout.h – Declares the layout class, isRoundEnabled property, and the JJCollectionViewDelegateRoundFlowLayout protocol.
• JJCollectionViewRoundFlowLayout.m – Contains the core layout logic that calculates section frames, registers the decoration view, and reads configuration models.
• JJCollectionViewRoundConfigModel.h – Defines the data model holding background color, corner radius, border, shadow, and image properties.
• Example/JJCollectionViewRoundFlowLayout/ThirdViewController.m – Provides a working implementation example demonstrating the delegate methods in a real view controller.

Summary

• JJCollectionViewRoundFlowLayout is a drop-in UICollectionViewFlowLayout subclass that adds rounded backgrounds via decoration views.
• Implement JJCollectionViewDelegateRoundFlowLayout and return a JJCollectionViewRoundConfigModel from collectionView:layout:configModelForSectionAtIndex: to configure colors, corner radius, borders, and shadows.
• Use collectionView:layout:borderEdgeInsertsForSectionAtIndex: to control padding between the background and section cells.
• The isRoundEnabled flag controls whether decoration views are rendered (defaults to YES).
• Touch animations are available through optional delegate methods returning JJCollectionViewTouchAnimationConfigModel.

Frequently Asked Questions

What iOS versions support JJCollectionViewRoundFlowLayout?

The library supports iOS 8.0 and later. Features like maskedCorners (for rounding specific corners) require iOS 11.0+, but the basic rounded background functionality works on all supported versions. The implementation uses standard UICollectionView decoration view APIs available since iOS 6.0.

Can I use different background styles for different sections?

Yes. The delegate methods receive the section index as a parameter, allowing you to return different JJCollectionViewRoundConfigModel instances for each section. You can vary background colors, corner radii, shadows, or even use images for some sections while keeping others plain by returning appropriately configured models based on the section index.

How do I adjust the spacing between the background and the cells?

Implement the optional delegate method collectionView:layout:borderEdgeInsertsForSectionAtIndex: and return UIEdgeInsets values. These insets apply specifically to the decorative background view, creating space between the rounded background rectangle and the cells inside that section, independent of the collection view's sectionInset property.

Is it possible to use an image instead of a solid color for the section background?

Yes. Set the bgImage property on the JJCollectionViewRoundConfigModel to a UIImage instance. When this property is populated, the layout draws the image within the section background frame instead of filling it with the solid backgroundColor. You can combine this with cornerRadius to create rounded image backgrounds, and the library handles the clipping appropriately.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}