<!--
{
  "availability" : [
    "iOS: 14.0.0 -",
    "iPadOS: 14.0.0 -",
    "macCatalyst: 14.0.0 -",
    "tvOS: 14.0.0 -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "UIKit",
  "identifier" : "/documentation/UIKit/UIConfigurationStateCustomKey",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "UIKit"
    ],
    "preciseIdentifier" : "c:@T@UIConfigurationStateCustomKey"
  },
  "title" : "UIConfigurationStateCustomKey"
}
-->

# UIConfigurationStateCustomKey

A key that defines a custom state for a view.

```
struct UIConfigurationStateCustomKey
```

## Overview

Create a custom state key if you want to define a custom state to include in a configuration state.

```objc
// Declare a custom key for a custom isArchived state (in the .h file). 
extern NSString* const UICONFIGURATIONSTATECUSTOMKEY_IS_ARCHIVED;

// Assign a value for the custom key for the custom isArchived state (in the .m file). 
NSString* const UICONFIGURATIONSTATECUSTOMKEY_IS_ARCHIVED = @"com.my-app.MyCell.isArchived";

// Declare a category on the cell state structure to provide a typed property for this custom state.
@interface UICellConfigurationState (MyCellAdditions)
- (BOOL)isArchived;
- (void)setIsArchived:(BOOL) isArchived;
@end

@implementation UICellConfigurationState (MyCellAdditions)
- (BOOL)isArchived {
    return [[self valueForKey:UICONFIGURATIONSTATECUSTOMKEY_IS_ARCHIVED] boolValue];
}

- (void)setIsArchived:(BOOL) isArchived {
    self[UICONFIGURATIONSTATECUSTOMKEY_IS_ARCHIVED] = @(isArchived);
}
@end

@interface MyCell : UICollectionViewCell
@property (nonatomic) BOOL isArchived;
@end

@implementation MyCell

// This is an existing custom property of the cell.
- (void)setIsArchived:(BOOL)isArchived {
    // Ensure that an update is performed whenever this property changes.
    if (isArchived != _isArchived) {
        _isArchived = isArchived;
        [self setNeedsUpdateConfiguration];
    }
}

- (UICellConfigurationState *)configurationState {
    // Get the structure from UIKit with the system properties set by calling super.
    UICellConfigurationState *state = [super configurationState];
    
    // Set the custom property on the state.
    [state setIsArchived: self.isArchived];
    return state;
}

- (void)updateConfigurationUsingState:(UICellConfigurationState *)state {
    // Get the default background configuration styling for the current state based on the system states.
    UIBackgroundConfiguration *backgroundConfig = [[UIBackgroundConfiguration listPlainCellConfiguration] updatedConfigurationForState:state];
    
    // Customize the background configuration based on the custom state.
    if (state.isArchived) {
        [backgroundConfig setVisualEffect:[UIBlurEffect effectWithStyle:UIBlurEffectStyleSystemMaterial]];
    }
    
    // Apply the background configuration to the cell.
    [self setBackgroundConfiguration:backgroundConfig];
}

@end
```

## Topics

### Creating a custom state key

[`init(_:)`](/documentation/UIKit/UIConfigurationStateCustomKey/init(_:))

Creates a custom state key.

[`init(rawValue:)`](/documentation/UIKit/UIConfigurationStateCustomKey/init(rawValue:))

Creates a custom state key with the specified raw value.

## Relationships

### Conforms To

[`RawRepresentable`](/documentation/Swift/RawRepresentable)

[`SendableMetatype`](/documentation/Swift/SendableMetatype)

[`Hashable`](/documentation/Swift/Hashable)

[`Sendable`](/documentation/Swift/Sendable)

[`Equatable`](/documentation/Swift/Equatable)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)