SwiftUI Hooks

A SwiftUI implementation of React Hooks.

Enhances reusability of stateful logic and gives state and lifecycle to function view.

📔 API Reference

• Introduction
• Getting Started
• Hooks API
• Rules of Hooks
• Building Your Own Hooks
• How to Test Your Custom Hooks
• Context
• License

Introduction

func timer() -> some View {
    let time = useState(Date())

    useEffect(.once) {
        let timer = Timer.scheduledTimer(withTimeInterval: 1, repeats: true) {
            time.wrappedValue = $0.fireDate
        }

        return {
            timer.invalidate()
        }
    }

    return Text("Time: \(time.wrappedValue)")
}

SwiftUI Hooks is a SwiftUI implementation of React Hooks. Brings the state and lifecycle into the function view, without depending on elements that are only allowed to be used in struct views such as @State or @ObservedObject.
It allows you to reuse stateful logic between views by building custom hooks composed with multiple hooks.
Furthermore, hooks such as useEffect also solve the problem of lack of lifecycles in SwiftUI.

The API and behavioral specs of SwiftUI Hooks are entirely based on React Hooks, so you can leverage your knowledge of web applications to your advantage.

There're already a bunch of documentations on React Hooks, so you can refer to it and learn more about Hooks.

• React Hooks Documentation
• Youtube Video

Getting Started

Requirements

Installation

The module name of the package is Hooks. Choose one of the instructions below to install and add the following import statement to your source code.

import Hooks

Xcode Package Dependency

From Xcode menu: File > Swift Packages > Add Package Dependency

https://github.com/ra1028/swiftui-hooks

Swift Package Manager

In your Package.swift file, first add the following to the package dependencies:

.package(url: "https://github.com/ra1028/swiftui-hooks"),

And then, include "Hooks" as a dependency for your target:

.target(name: "<target>", dependencies: [
    .product(name: "Hooks", package: "swiftui-hooks"),
]),

Documentation

• API Reference
• Example apps

Hooks API

👇 Click to open the description.

func useState<State>(_ initialState: State) -> Binding<State>
func useState<State>(_ initialState: @escaping () -> State) -> Binding<State>

let count = useState(0)  // Binding<Int>

Button("Increment") {
    count.wrappedValue += 1
}

let count = useState {
    let initialState = expensiveComputation() // Int
    return initialState
}                                             // Binding<Int>

Button("Increment") {
    count.wrappedValue += 1
}

func useEffect(_ updateStrategy: HookUpdateStrategy? = nil, _ effect: @escaping () -> (() -> Void)?)

useEffect {
    print("Do side effects")

    return {
        print("Do cleanup")
    }
}

func useLayoutEffect(_ updateStrategy: HookUpdateStrategy? = nil, _ effect: @escaping () -> (() -> Void)?)

useLayoutEffect {
    print("Do side effects")
    return nil
}

func useMemo<Value>(_ updateStrategy: HookUpdateStrategy, _ makeValue: @escaping () -> Value) -> Value

let random = useMemo(.once) {
    Int.random(in: 0...100)
}

func useRef<T>(_ initialValue: T) -> RefObject<T>

let value = useRef("text")  // RefObject<String>

Button("Save text") {
    value.current = "new text"
}

func useReducer<State, Action>(_ reducer: @escaping (State, Action) -> State, initialState: State) -> (state: State, dispatch: (Action) -> Void)

enum Action {
    case increment, decrement
}

func reducer(state: Int, action: Action) -> Int {
    switch action {
        case .increment:
            return state + 1

        case .decrement:
            return state - 1
    }
}

let (count, dispatch) = useReducer(reducer, initialState: 0)

func useAsync<Output>(_ updateStrategy: HookUpdateStrategy, _ operation: @escaping () async -> Output) -> AsyncPhase<Output, Never>
func useAsync<Output>(_ updateStrategy: HookUpdateStrategy, _ operation: @escaping () async throws -> Output) -> AsyncPhase<Output, Error>

let phase = useAsync(.once) {
    try await URLSession.shared.data(from: url)
}

func useAsyncPerform<Output>(_ operation: @escaping @MainActor () async -> Output) -> (phase: AsyncPhase<Output, Never>, perform: @MainActor () async -> Void)
func useAsyncPerform<Output>(_ operation: @escaping @MainActor () async throws -> Output) -> (phase: AsyncPhase<Output, Error>, perform: @MainActor () async -> Void)

let (phase, perform) = useAsyncPerform {
    try await URLSession.shared.data(from: url)
}

func usePublisher<P: Publisher>(_ updateStrategy: HookUpdateStrategy, _ makePublisher: @escaping () -> P) -> AsyncPhase<P.Output, P.Failure>

let phase = usePublisher(.once) {
    URLSession.shared.dataTaskPublisher(for: url)
}

func usePublisherSubscribe<P: Publisher>(_ makePublisher: @escaping () -> P) -> (phase: AsyncPhase<P.Output, P.Failure>, subscribe: () -> Void)

let (phase, subscribe) = usePublisherSubscribe {
    URLSession.shared.dataTaskPublisher(for: url)
}

func useEnvironment<Value>(_ keyPath: KeyPath<EnvironmentValues, Value>) -> Value

let colorScheme = useEnvironment(\.colorScheme)  // ColorScheme

func useContext<T>(_ context: Context<T>.Type) -> T

let value = useContext(Context<Int>.self)  // Int

See also: React Hooks API Reference

Rules of Hooks

In order to take advantage of the wonderful interface of Hooks, the same rules that React hooks has must also be followed by SwiftUI Hooks.

[Disclaimer]: These rules are not technical constraints specific to SwiftUI Hooks, but are necessary based on the design of the Hooks itself. You can see here to know more about the rules defined for React Hooks.

* In -Onone builds, if a violation against this rules is detected, it asserts by an internal sanity check to help the developer notice the mistake in the use of hooks. However, hooks also has disableHooksRulesAssertion modifier in case you want to disable the assertions.

Only Call Hooks at the Function Top Level

Do not call Hooks inside conditions or loops. The order in which hook is called is important since Hooks uses LinkedList to keep track of its state.

🟢 DO

@ViewBuilder
func counterButton() -> some View {
    let count = useState(0)  // 🟢 Uses hook at the top level

    Button("You clicked \(count.wrappedValue) times") {
        count.wrappedValue += 1
    }
}

🔴 DON'T

@ViewBuilder
func counterButton() -> some View {
    if condition {
        let count = useState(0)  // 🔴 Uses hook inside condition.

        Button("You clicked \(count.wrappedValue) times") {
            count.wrappedValue += 1
        }
    }
}

Only Call Hooks from HookScope or HookView.hookBody

In order to preserve the state, hooks must be called inside a HookScope.
A view that conforms to the HookView protocol will automatically be enclosed in a HookScope.

🟢 DO

struct CounterButton: HookView {  // 🟢 `HookView` is used.
    var hookBody: some View {
        let count = useState(0)

        Button("You clicked \(count.wrappedValue) times") {
            count.wrappedValue += 1
        }
    }
}

func counterButton() -> some View {
    HookScope {  // 🟢 `HookScope` is used.
        let count = useState(0)

        Button("You clicked \(count.wrappedValue) times") {
            count.wrappedValue += 1
        }
    }
}

struct ContentView: HookView {
    var hookBody: some View {
        counterButton()
    }

    // 🟢 Called from `HookView.hookBody` or `HookScope`.
    @ViewBuilder
    var counterButton: some View {
        let count = useState(0)

        Button("You clicked \(count.wrappedValue) times") {
            count.wrappedValue += 1
        }
    }
}

🔴 DON'T

// 🔴 Neither `HookScope` nor `HookView` is used, and is not called from them.
@ViewBuilder
func counterButton() -> some View {
    let count = useState(0)

    Button("You clicked \(count.wrappedValue) times") {
        count.wrappedValue += 1
    }
}

See also: Rules of React Hooks

Building Your Own Hooks

Building your own hooks lets you extract stateful logic into reusable functions.
Hooks are composable since they serve as a stateful functions. So, they can be able to compose with other hooks to create your own custom hook.

In the following example, the most basic useState and useEffect are used to make a function provides a current Date with the specified interval. If the specified interval is changed, Timer.invalidate() will be called and then a new timer will be activated.
Like this, the stateful logic can be extracted out as a function using Hooks.

func useTimer(interval: TimeInterval) -> Date {
    let time = useState(Date())

    useEffect(.preserved(by: interval)) {
        let timer = Timer.scheduledTimer(withTimeInterval: interval, repeats: true) {
            time.wrappedValue = $0.fireDate
        }

        return {
            timer.invalidate()
        }
    }

    return time.wrappedValue
}

Let's refactor the Example view at the beginning of the README using this custom hook.

struct Example: HookView {
    var hookBody: some View {
        let time = useTimer(interval: 1)

        Text("Now: \(time)")
    }
}

It's so much easier to read and less codes!
Of course the stateful custom hook can be called by arbitrary views.

See also: Building Your Own React Hooks

How to Test Your Custom Hooks

So far, we have explained that hooks should be called within HookScope or HookView. Then, how can the custom hook you have created be tested?
To making unit testing of your custom hooks easy, SwiftUI Hooks provides a simple and complete test utility library.

HookTester enables unit testing independent of UI of custom hooks by simulating the behavior on the view of a given hook and managing the result values.

Example:

// Your custom hook.
func useCounter() -> (count: Int, increment: () -> Void) {
    let count = useState(0)

    func increment() {
        count.wrappedValue += 1
    }

    return (count: count.wrappedValue, increment: increment)
}

let tester = HookTester {
    useCounter()
}

XCTAssertEqual(tester.value.count, 0)

tester.value.increment()

XCTAssertEqual(tester.value.count, 1)

tester.update()  // Simulates view's update.

XCTAssertEqual(tester.value.count, 1)

Context

React has a way to pass data through the component tree without having to pass it down manually, it's called Context.
Similarly, SwiftUI has EnvironmentValues to achieve the same, but defining a custom environment value is a bit of a pain, so SwiftUI Hooks provides Context API that a more user-friendly.
This is a simple wrapper around the EnvironmentValues.

typealias ColorSchemeContext = Context<Binding<ColorScheme>>

struct ContentView: HookView {
    var hookBody: some View {
        let colorScheme = useState(ColorScheme.light)

        ColorSchemeContext.Provider(value: colorScheme) {
            darkModeButton
                .background(Color(.systemBackground))
                .colorScheme(colorScheme.wrappedValue)
        }
    }

    var darkModeButton: some View {
        ColorSchemeContext.Consumer { colorScheme in
            Button("Use dark mode") {
                colorScheme.wrappedValue = .dark
            }
        }
    }
}

And of course, there is a useContext hook that can be used instead of Context.Consumer to retrieve the provided value.

@ViewBuilder
var darkModeButton: some View {
    let colorScheme = useContext(ColorSchemeContext.self)

    Button("Use dark mode") {
        colorScheme.wrappedValue = .dark
    }
}

See also: React Context

Acknowledgements

• React Hooks
• Flutter Hooks

License

MIT © Ryo Aoyama