ComposeHooks

English | 简体中文

Star History

KMP Support

NOTE: The artifact id is hooks2

implementation("xyz.junerver.compose:hooks2:<latest_release>")

Currently only limited targets are supported:

• android
• desktop (jvm)
• iosarm64
• iosimulatorarm64
• iosx64

About

The idea for the project comes from alibaba/hooks, which is a very easy-to-use collection of React Hooks.

It encapsulates most common operations as custom hooks, and useRequest is the top priority. It is designed to be very lightweight, highly configurable, and easy to use.

Therefore, based on this design idea, Hooks that can be used in the Compose project were created using similar API names.

The hooks that have been implemented so far are as follows:

Note: All use functions also have the signature of remember. If you prefer Compose’s naming method, just use rememberXxx!

Hooks

State

hook name	description
useAutoReset	A hook which will reset state to the default value after some time.
useBoolean	Hook to manage boolean state.
useContext	just like react
useCreation	useCreation is the replacement for useRef.
useDebounce	A hook that deal with the debounced value.
Form.useForm	A Hook that can easier control headless component Form
useGetState	A Hooks that handle state using destructuring declaration syntax.
useImmutableList	A hook for managing immutable lists in Compose.
useLastChanged	A Hook that records the Instant of the last change
useLatest	A Hook that returns the latest value, effectively avoiding the closure problem.
usePersistent	A lightweight persistence hook, you need to implement the persistence method yourself (memory persistence is used by default)
usePrevious	A Hook to return the previous state.
useReducer	just like react
useRef	just like react
useResetState	A hook for managing state with reset functionality.
useSelectable	A utility function to help implement select or multi select feature.
useSelector/useDispatch	easier to management global state，just like use redux-react
useState	just like react
useStateMachine	A Compose Hook for managing state machines
useThrottle	A hook that deal with the throttled value.
useToggle	A hook that toggle states.

Effect

hook name	description
useBackToFrontEffect & useFrontToBackEffect	Execute effect when app goes to the background or come back to the foreground
useEffect	just like react
useDebounceEffect	Debounce your useEffect.
useThrottleEffect	Throttle your useEffect.
useUpdateEffect	A hook alike useEffect but skips running the effect for the first time.
usePausableEffect	A pausable effect hook that provides the ability to pause, resume, and stop effect execution

LifeCycle

hook name	description
useMount	A hook that executes a function after the component is mounted.
useUnmount	A hook that executes the function right before the component is unmounted.

Time

hook name	description
useDateFormat	Get the formatted date according to the string of tokens passed in, inspired by dayjs.
useInterval	A hook that handles the setInterval timer function.
useNow	A hook that return now date, default format: yyyy-MM-dd HH:mm:ss
useTimeAgo	Reactive time ago. Automatically update the time ago string when the time changes.
useTimeout	A hook that handles the setTimeout timer function.
useTimeoutFn	A hook for executing a function after a specified delay with controls.
useTimeoutPoll	Use timeout to poll for content. Triggers the callback after the last task is completed.
useTimestamp	A hook that return now timestamp as a reactive state.

Math

hook name	description
Reactive kotlin.math.abs.
useCeil	Reactive kotlin.math.ceil
useRound	Reactive kotlin.math.round
useTrunc	Reactive kotlin.math.truncate
useMin	Reactive kotlin.math.min
useMax	Reactive kotlin.math.max
usePow	Reactive kotlin.math.pow
useSqrt	Reactive kotlin.math.sqrt

Utilities

hook name	description
useAsync	A hook that encapsulates rememberCoroutineScope to make it easier to use coroutines
useBiometric*	use biometrics conveniently
useBatteryInfo*	A hook that can get the battery level and if is charging.
useBuildInfo*	A hook that can get the brand, model, and version of android.
useClipboard	Easy to use Clipboard
useCountdown	A hook for manage countdown.
useCounter	A hook that manage counter.
useCycleList	Cycle through a list of items.
useDebounceFn	A hook that deal with the debounced function.
useDisableScreenshot*	A hook used to handle the prohibition of screenshots on privacy pages.
useEvent	Implement lightweight cross-component communication using the subscribe-publish pattern
useFlashlight*	A Hook for convenient use of flashlight.
useIdel	Tracks whether the user is being inactive.
useKeyboard	A Hook that controls the display and hiding of the soft keyboard.
useNetwork*	A hook for obtaining network connection status and type.
useRequest	Manage network requests and implement: manual and automatic triggering; life cycle callbacks; refresh; mutate changes; cancel requests; polling; Ready; dependency refresh; debounce, throttle; error retry;
useScreenInfo*	A hook that obtains information about the screen width, height, horizontal and vertical orientation.
useSorted	A hook that helps you reactive sort array
useThrottleFn	A hook that deal with the throttled function.
useUndo	A Hook for handling undo and redo.
useUpdate	A hook that returns a function which can be used to force the component to re-render.
useVibrate*	A hook that make using vibration feedback easy

Functions marked with * can only be used on Android

Add to dependencies

KMP project

// groovy
implementation 'xyz.junerver.compose:hooks2:<latest_release>'
// kotlin
implementation("xyz.junerver.compose:hooks2:<latest_release>")

Use hooks2 In Android

For pure Android projects, please use the following dependencies（Artifact id：hooks2-android）：

implementation("xyz.junerver.compose:hooks2-android:<latest_release>")

If used in ComposeMultiplatform, use artifact id: hooks2

Old version hooks continue to support

If your project does not have performance issues due to recompose , you can continue to use the old version in the Android project, and the bugfix will be synchronized to the old version in subsequent development.

implementation("xyz.junerver.compose:hooks:2.0.3")

Quick Setup

1. Use useGetState to quickly create controlled components

   val (name, setName, getName) = useGetState("")
   OutlinedTextField(
       value = getName(), // or `name.value`
       onValueChange = setName,
       label = { Text("Input Name") }
   )

2. Use useEffect to perform component LaunchedEffects

3. Use useRef to create object references that are not affected by component recompose

   val countRef = useRef(0) // or `val countRef by useRef(0)`
   Button(onClick = {
       countRef.current += 1 // or `countRef += 1`
       println(countRef)
   }) {
       Text(text = "Ref= ${countRef.current}") // or `countRef`
   }

4. Use useRequest to easily manage network query state

   val (dataState, loadingState, errorState, run) = useRequest(
       requestFn = WebService::login.asRequestFn(), //Encapsulate the corresponding extension functions yourself,to make retrofit friendly
       optionsOf = {
           manual = true
       }
   )
   val data by dataState // obtained `value` through delegate
   val loading  by loadingState
   val error by errorState
   if (loading) {
       Text(text = "loading ....")
   }
   if (data != null) {
       Text(text = "resp: $data")
   }
   if (error != null) {
       Text(text = "error: $error")
   }
   Button(onClick = { run(arrayOf(requestBody)) }) {
       Text(text = "Login")
   }

   useRequest organizes code through a plug-in pattern, the core code is extremely simple, and can be easily extended for more advanced features. Current features include:

   • Automatic/manual request
   • Polling
   • Debounce
   • Throttle
   • Error retry
   • Loading delay
   • SWR(stale-while-revalidate)
   • Caching

For more usage, please refer to wiki and examples

Live Templates

Copy hooks in the Live Templates directory File, paste into C:\Users\<user-name>\AppData\Roaming\Google\AndroidStudio2023.2\templates\

You can easily create code snippets of useState and useRequest through us and ur.

Open Inlay Hints for Kotlin Type

For hooks like useRequest, its return value can deconstruct many objects and functions. It is necessary to enable InlayHint:

Editor - Inlay Hints - Types - Kotlin

ProGuard

If you are using ProGuard you might need to add the following option:

-keep class xyz.junerver.composehooks.** { *; }
-keepclassmembers class xyz.junerver.composehooks.** { *; }
-dontwarn xyz.junerver.composehooks.**

Documentation

• Easily manage network requests with useRequest
• Using state hoisting in Compose? I'll hoisting to Provider
• How does a parent component call the function of a child component in Compose?
• How to use MVI idea conveniently in Compose? Try useReducer!
• Easily manage global state in Compose like using redux
• Easily use asynchronous dispatch to manage global state in Compose
• Managing network requests in Compose is so easy!
• Use debounce and throttle elegantly in Jetpack Compose

Todo:

• KMP friendly
• CI
• Unit Test
• Complete documentation

参考/Thanks

1. alibaba/hooks
2. pavi2410/useCompose
3. vueuse/vueuse

Contributing Guidelines

Contributing guidelines

License

Apache License 2.0