Component Styling

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

Component-Level

Element-Level

Reference: Allowed IDs

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

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.

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.

// 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

Support

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

Best Practices

Token First

Progressive Specificity

Consistency

Auditable Changes

Dark Mode QA

Minimal Exclusions

Overriding Navigation Behaviour

Behaviour Architecture

Override Example: Story Tab Navigation

Advanced iOS Navigation (Swipe Back & SwiftUI Hosting)

When to Escalate

Next Steps

Dynamic UI

Advanced Customization

Powered by

Getting Started

Customization

Components

Support

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

​Best Practices

Token First

Progressive Specificity

Consistency

Auditable Changes

Dark Mode QA

Minimal Exclusions

​Overriding Navigation Behaviour

​Behaviour Architecture

​Override Example: Story Tab Navigation

​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

Best Practices

Overriding Navigation Behaviour

Behaviour Architecture

Override Example: Story Tab Navigation

Advanced iOS Navigation (Swipe Back & SwiftUI Hosting)

When to Escalate

Next Steps