Component Styling - social.plus

For teams who need deeper styling control while staying within the UIKit framework. Component Styling allows you to override CSS, customize individual components, and implement advanced theming.

Styling Control

Override styles with custom config json

Component Targeting

Customize specific components and pages

Advanced Theming

Complex color schemes and typography

UIKit Framework

Still within the UIKit ecosystem

When to Choose Component Styling

Component Styling is ideal when you need: ✅ Custom brand experiences - Basic colors and fonts
✅ Granular control - Target specific components or pages
✅ Advanced theming - Complex color schemes and typography
✅ Framework benefits - Want to stay within UIKit’s ecosystem ❌ Simple branding - Dynamic UI is easier for basic needs
❌ Complex layouts - Fork & Extend offers more freedom
❌ Custom components - Need source code access for new components

Configuration Model

Component Styling uses a single config.json surface for cross-platform overrides. It layers on top of default UIKit tokens (and Dynamic UI if present) using a path pattern: page_id/component_id/element_id with wildcards (*).

Path Pattern & Levels

Level	Example	Description	Wildcard Use
Page	`camera_page//`	Entire screen / route	Replace component & element with `/`
Component	`/comment_tray_component/`	Functional unit within a page	Wildcard page to apply globally
Element	`story_page/*/close_button`	Single interactive / visual element	Wildcard component for all instances

Specific beats generic: Element overrides > Component overrides > Page overrides > Global theme.

Supported Theme Tokens

Token	Purpose	Notes
primary_color	Actions / highlights	High contrast vs background
secondary_color	Secondary actions / borders	Complementary to primary
base_color	Primary text color	Body & headings
base_shade1_color	Secondary text	Subtitles / meta
base_shade2_color	Tertiary text / hints	Placeholders, inactive
base_shade3_color	Disabled text	Low emphasis
base_shade4_color	Optional faint text / separators	Lowest emphasis
alert_color	Errors / destructive	Distinct from brand palette
background_color	Surface background	Page / component surface

Minimal Config Skeleton

{
  "preferred_theme": "default",
  "theme": {
    "light": { "primary_color": "#1054DE", "background_color": "#FFFFFF" },
    "dark": { "primary_color": "#1054DE", "background_color": "#191919" }
  },
  "excludes": [],
  "customizations": {}
}

Theme Application & Preferred Mode

Set the app’s theme resolution strategy with preferred_theme:

Value	Behavior
default	Follow OS setting (light/dark)
light	Force light regardless of OS
dark	Force dark regardless of OS

Use default unless you have a business requirement to lock theme (e.g., brand guidelines for launch).

Targeting Examples

Page-Level

Override a whole screen. Great for hero / camera / immersive surfaces.

"select_target_page/*/*": { "title": "Share To" }

Component-Level

Adjust reusable functional blocks everywhere.

"*/edit_comment_component/*": { "theme": { "light": { "primary_color": "#1254DE" } } }

Element-Level

Fine-grain tweak for single control.

"story_page/*/story_comment_button": {
  "comment_icon": "comment.png",
  "background_color": "#1234DD"
}

Reference: Allowed IDs

Pages
Components
Elements (Partial)

select_target_page/*/*
camera_page/*/*
create_story_page/*/*
story_page/*/*

*/edit_comment_component/*
*/comment_tray_component/*
*/story_tab_component/*
*/hyper_link_config_component/*

select_target_page/*/back_button
camera_page/*/close_button
create_story_page/*/back_button
create_story_page/*/aspect_ratio_button
create_story_page/*/story_hyperlink_button
create_story_page/*/hyper_link
create_story_page/*/share_story_button
story_page/*/progress_bar
story_page/*/overflow_menu
story_page/*/close_button
story_page/*/story_impression_button
story_page/*/story_comment_button
story_page/*/story_reaction_button
story_page/*/create_new_story_button
story_page/*/speaker_button
*/edit_comment_component/cancel_button
*/edit_comment_component/save_button
*/hyper_link_config_component/done_button
*/hyper_link_config_component/cancel_button
*/story_tab_component/story_ring
*/story_tab_component/create_new_story_button
*/*/close_button

List may expand in future versions; avoid hard-coding validation exclusively to this snapshot.

Exclusions

Remove (hide) specific elements by adding their path to excludes:

"excludes": [
  "create_story_page/*/aspect_ratio_button"
]

Excluding structural elements (like a required close button) may degrade usability. Test flows after any exclusion.

Precedence & Conflict Resolution

Scenario	Winning Value
Page vs Global	Page override
Component vs Page	Component override
Element vs Component	Element override
Multiple matches same level	Last in file (bottom-most)

Group related overrides together to prevent accidental shadowing by later blocks.

Custom Config File (iOS)

iOS only. On Android, Flutter, and React Native, the config JSON is loaded differently per platform. On iOS, use setConfigFile to load a local JSON file from your app bundle at initialisation time.

By default UIKit reads its bundled config.json. setConfigFile lets you supply a replacement from your own app bundle — useful for per-environment configs, white-label builds, or shipping your own defaults without modifying UIKit source.

Implementation

import AmityUIKit4

func setupUIKit() {
    AmityUIKit4Manager.setup(client: AmityUIKitManager.client)

    // Load a custom config.json from the app bundle
    if let filePath = Bundle.main.path(forResource: "AmityUIKitConfig", ofType: "json") {
        AmityUIKit4Manager.setConfigFile(filePath)
    }
}

Call setConfigFile before presenting any UIKit view. Config values are read at render time — calling it after the first render may leave some components using the default config.

Parameter	Type	Description
`filePath`	`String`	Absolute path to your `config.json` file. Use `Bundle.path(forResource:ofType:)` to resolve it safely.

If the file path is invalid or the JSON is malformed, UIKit silently falls back to its bundled defaults. Validate your JSON locally before shipping.

Custom Asset Bundle (iOS)

iOS only. On Android, Flutter, and React Native, image overrides are handled through the config.json element keys (e.g. “close_icon”: “close.png”).

In addition to config.json, iOS lets you supply a custom Bundle containing your own images. UIKit uses it as a fallback — your assets are loaded only for image names that do not exist in UIKit’s own bundle.

If you provide an image with the same name as a UIKit default asset, UIKit’s copy wins. To replace an exposed icon, point its config.json key to a uniquely named file and provide that file in your custom bundle.

How It Works

UIKit bundle checked first

If the image name exists in UIKit’s own bundle, that version is always used.

Custom bundle as fallback

Only when the name is not found in UIKit’s bundle does it fall through to your registered custom bundle.

Not found anywhere

If the image is absent from both bundles, UIKit renders a placeholder rather than crashing.

Implementation

Basic Setup
With Config File
Dedicated Bundle

Call setCustomAssetBundle once during app initialisation, after AmityUIKit4Manager.setup(client:).

import AmityUIKit4

func setupUIKit() {
    AmityUIKit4Manager.setup(client: AmityUIKitManager.client)

    // Register your app's main bundle as the custom asset source
    AmityUIKit4Manager.setCustomAssetBundle(bundle: .main)
}

Combine bundle registration with a custom config.json so UIKit resolves icon keys to your asset names.

func setupUIKit() {
    AmityUIKit4Manager.setup(client: AmityUIKitManager.client)

    if let filePath = Bundle.main.path(forResource: "AmityUIKitConfig", ofType: "json") {
        AmityUIKit4Manager.setConfigFile(filePath)
    }

    AmityUIKit4Manager.setCustomAssetBundle(bundle: .main)
}

UIKit looks for my_close_icon.png in its own bundle first. Since that name does not exist there, it falls back to your custom bundle where the file is found.

For modular apps where assets live in a Swift Package or framework bundle, pass that bundle instead of Bundle.main.

// Bundle.module is generated automatically by SwiftPM
AmityUIKit4Manager.setCustomAssetBundle(bundle: .module)

Register the bundle before any UIKit view is presented. Images are resolved at render time — late registration may cause some views to display the wrong asset.

Troubleshooting

Image is not showing

Verify the asset is included in the bundle you registered:

let url = AmityUIKit4Manager.customAssetBundle?
    .url(forResource: "my_icon", withExtension: "png")
print(url ?? "not found in custom bundle")

Check that the file name, extension, and capitalisation match exactly what is referenced in config.json.

UIKit is displaying its default icon instead of mine

An asset with the same name in UIKit’s bundle always wins. Rename your asset uniquely and update the matching config.json icon key to point to the new name.

Works in Debug but missing in Release

Ensure the image file appears under Copy Bundle Resources in Build Phases. Loose PNG/PDF files (not inside an .xcassets catalog) must be added manually.

Best Practices

Token First

Change global tokens before per-element overrides.

Progressive Specificity

Escalate from page → component → element only when needed.

Consistency

Reuse colors; avoid random hex proliferation.

Auditable Changes

Document rationale in PR descriptions.

Dark Mode QA

Visually inspect every high-contrast surface.

Minimal Exclusions

Prefer styling adjustments over removal.

Navigation can be customized without forking by overriding the provided Behaviour classes. UIKit isolates navigation & event hooks into behaviour objects per page/component so you can inject custom flows (e.g., presenting a different creation screen, analytics, guards) while keeping styling overrides separate.

Behaviour Architecture

Each major screen/component exposes a Behaviour (iOS) / Behavior (Android) class with overridable navigation methods.
A top-level AmityUIKit4Manager.behaviour (iOS) / AmityUIKit4Manager.behavior (Android) aggregates these instances.
Replace only the concrete behaviour you need; leave others at default.

Override Example

// Custom behaviour for Story Tab component
class CustomStoryTabComponentBehaviour: AmityStoryTabComponentBehaviour {
  override init() { super.init() }

  override func goToViewStoryPage(context: AmityStoryTabComponentBehaviour.Context) {
    // Custom navigation (e.g., analytics, gated modal, custom host)
  }

  override func goToCreateStoryPage(context: AmityStoryTabComponentBehaviour.Context) {
    // Present alternative creation UI or permission flow
  }
}

// Register once (e.g. after SDK init)
func configureNavigationOverrides() {
  AmityUIKit4Manager.behaviour.storyTabComponentBehaviour = CustomStoryTabComponentBehaviour()
}

Only override the specific methods you need; keep defaults for forward compatibility.

UIKit v4 pages are predominantly SwiftUI, embedded in UINavigationController via helper controllers:

Class	Purpose
`AmitySwiftUIHostingController`	Wrap a single SwiftUI view
`AmitySwiftUIHostingNavigationController`	Provide a navigation stack hosting SwiftUI pages

To preserve the interactive swipe‑to‑go‑back gesture while customizing appearance, UIKit globally overrides navigation gesture delegate methods. You can supply your own gesture behaviour logic via AmitySwipeToBackGestureBehavior.

// Default usage
let defaultGestureBehavior = AmitySwipeToBackGestureBehavior()

// Custom gesture policy
class CustomSwipeBackGestureBehavior: AmitySwipeToBackGestureBehavior {
  override func gestureRecognizerShouldBegin(
    navigationController: UINavigationController,
    _ gestureRecognizer: UIGestureRecognizer
  ) -> Bool {
    // Example: disable swipe on root page or during modal overlay
    return navigationController.viewControllers.count > 1
  }

  override func gestureRecognizer(
    _ gestureRecognizer: UIGestureRecognizer,
    shouldRecognizeSimultaneouslyWith otherGestureRecognizer: UIGestureRecognizer
  ) -> Bool {
    // Allow simultaneous recognition with horizontally scrollable carousels
    return true
  }
}

func configureGestureBehavior() {
  AmityUIKit4Manager.behaviour.swipeToBackGestureBehavior = CustomSwipeBackGestureBehavior()
}

Keep gesture logic lightweight—long operations here can block UI responsiveness.

When to Escalate

If navigation changes require altering internal view composition (e.g., embedding a new container architecture), consider moving to Fork & Extend. Simple route substitutions, analytics, permission gates, and gesture tweaks belong here.

Powered by

Getting Started

Customization

Components

Release Notes

Support

Documentation Index

Styling Control

Component Targeting

Advanced Theming

UIKit Framework

​When to Choose Component Styling

​Configuration Model

​Path Pattern & Levels

​Supported Theme Tokens

​Minimal Config Skeleton

​Theme Application & Preferred Mode

​Targeting Examples

​Reference: Allowed IDs

​Exclusions

​Precedence & Conflict Resolution

​Custom Config File (iOS)

​Implementation

​Custom Asset Bundle (iOS)

​How It Works

​Implementation

​Troubleshooting

​Best Practices

Token First

Progressive Specificity

Consistency

Auditable Changes

Dark Mode QA

Minimal Exclusions

​Overriding Navigation Behaviour

​Behaviour Architecture

​Override Example

​Advanced iOS Navigation (Swipe Back & SwiftUI Hosting)

​When to Escalate

​Next Steps

Dynamic UI

Advanced Customization

When to Choose Component Styling

Configuration Model

Path Pattern & Levels

Supported Theme Tokens

Minimal Config Skeleton

Theme Application & Preferred Mode

Targeting Examples

Reference: Allowed IDs

Exclusions

Precedence & Conflict Resolution

Custom Config File (iOS)

Implementation

Custom Asset Bundle (iOS)

How It Works

Implementation

Troubleshooting

Best Practices

Overriding Navigation Behaviour

Behaviour Architecture

Override Example

Advanced iOS Navigation (Swipe Back & SwiftUI Hosting)

When to Escalate

Next Steps