---
url: https://react-simplikit.slash.page/core/ai-integration.md
description: Use react-simplikit with AI coding agents
---

# AI Integration

react-simplikit ships a few things that let an AI coding agent (Claude Code, Codex, Cursor and others) find the right hook instead of hand-writing it.

## Agent skill

The `react-simplikit` skill is a short catalog of every hook, component and util with a one-line description, plus rules about imports and SSR. Once installed, the agent consults it before writing debounce, throttle, click-outside, keyboard-avoidance and similar logic, and reads the bundled reference page before using an entry.

::: code-group

```sh [skills.sh]
npx skills add toss/react-simplikit --skill react-simplikit
```

```sh [Claude Code]
claude plugin marketplace add https://github.com/toss/react-simplikit --sparse .claude-plugin packages/plugin
claude plugin install react-simplikit@react-simplikit
```

```sh [Codex]
codex plugin marketplace add https://github.com/toss/react-simplikit
# then install "react-simplikit" from the plugin UI
```

:::

The skill is generated from these documentation pages, so it stays in sync with the library. Its source lives in [`packages/plugin`](https://github.com/toss/react-simplikit/tree/main/packages/plugin).

## llms.txt

The documentation is also published in the formats agents read directly:

* [`/llms.txt`](https://react-simplikit.slash.page/llms.txt) — an index of every page with a one-line summary
* [`/llms-full.txt`](https://react-simplikit.slash.page/llms-full.txt) — the whole documentation in one file
* Any page with a `.md` suffix returns raw Markdown, for example [`/core/hooks/useDebounce.md`](https://react-simplikit.slash.page/core/hooks/useDebounce.md)

## Context7

react-simplikit is indexed on [Context7](https://context7.com/toss/react-simplikit) as `/toss/react-simplikit`. Agents with the Context7 MCP server can query the documentation from there without any setup on your side.

---

---
url: https://react-simplikit.slash.page/core/utils/buildContext.md
---
# buildContext

`buildContext` is a helper function that reduces repetitive code when defining React Context.

## Interface

```ts
function buildContext(
  contextName: string,
  defaultContextValues: ContextValuesType
): [
  Provider: (props: ProviderProps<ContextValuesType>) => JSX.Element,
  useContext: () => ContextValuesType,
];
```

### Parameters

### Return Value

## Example

```tsx
const [Provider, useContext] = buildContext<{ title: string }>(
  'TestContext',
  null
);

function Inner() {
  const { title } = useContext();
  return <div>{title}</div>;
}

function Page() {
  return (
    <Provider title="Hello">
      <Inner />
    </Provider>
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/contributing.md
---
# Contributing to react-simplikit

`react-simplikit` is designed to encourage contributions from anyone. If you'd like to contribute, please follow the guide below.

## Package Scope

`react-simplikit` focuses on **platform-independent hooks, components, and utilities** that work across all JavaScript environments (browser, server, React Native, etc.).

Before contributing, check which package your implementation belongs to:

| Package                         | Scope                                  | Examples                                                     |
| ------------------------------- | -------------------------------------- | ------------------------------------------------------------ |
| `react-simplikit`               | Platform-independent pure state/logic  | `useToggle`, `useAsyncEffect`, `useLoading`                  |
| Mobile utilities (`src/mobile`) | Solving mobile web-specific challenges | `useAvoidKeyboard`, `useBodyScrollLock`, `useVisualViewport` |

::: tip
The mobile package is **not** for all browser API-dependent hooks. It specifically targets **problems encountered in mobile web environments** (viewport management, keyboard handling, layout issues on iOS Safari and Android Chrome). For example, a keyboard shortcut hook uses browser APIs but doesn't belong in the mobile package.
:::

## Implementation Contribution

When contributing implementations, add them to the appropriate directory based on their type (`components`, `hooks`, or `utils`). Each implementation must include the following elements:

* **Implementation**
* **Test Code**
* **JSDoc**

::: tip
**Do I need to write documentation?**

No, you don't need to write documentation separately. Instead, please write detailed JSDoc comments, then run `yarn docs:gen <name>` to generate the English documentation from them and commit the result with your PR. Translations are maintained separately; until one exists, the page is shown in English with a notice.
:::

### Writing Implementations

You must follow `react-simplikit`'s [Design Principles](./design-principles.md). We don't provide implementations that depend on specific libraries or are tightly coupled with React's lifecycle. Please write implementations that adhere to these design principles.

### Writing JSDoc

All implementations must include [JSDoc](https://jsdoc.app/) comments. These provide hints when using the implementation and play a crucial role in generating documentation.
JSDoc comments must include `@description` and `@example`, and if there are parameters or return values, they should include `@param` and `@returns`.

::: details JSDoc writing rules must be followed for accurate documentation generation. If JSDoc validation fails, CI might fail.

* JSDoc must be written in English.

* `@description`: A required tag that clearly explains the implementation's functionality or role.

* `@example`: A required tag that shows example code demonstrating how to use the implementation.

* `@param`: Write the parameter's name and description. Must be included if the implementation has parameters.

  * For required parameters: `@param {<type>} <parameter name> - <parameter description>`
  * For optional parameters: `@param {<type>} [<parameter name>] - <parameter description>`
  * For object parameters, both the object itself and its properties need `@param` tags.
  * If you want to write a list under a description, use `--` instead of `-`.

    ```ts
    type Props = {
      name: string;
      age: number;
      nickname?: string;
      company: {
        name: string;
        address?: string;
      };
      paymentMethod?: {
        type: 'card' | 'account';
        number?: string;
      };
    };

    /**
     * @param {string} name - Name of the user.
     * @param {number} age - Age of the user.
     * @param {string} [nickname] - Nickname of the user.
     * @param {Object} company - Company information of the user.
     * @param {string} company.name - Name of the company.
     * @param {string} [company.address] - Address of the company.
     * @param {Object} [paymentMethod] - Payment information of the user.
     * @param {string} [paymentMethod.type] - Payment method.
     * @param {string} [paymentMethod.number] - Card or account number.
     *   -- Card or account number without `-`.
     *   -- If the number is a card number, it should be 15 or 16 digits.
     */
    ```

    This JSDoc will be converted into the following documentation.

* `@returns`: Write the return value's name and description. Must be included if the implementation has return values.

  * Format: `@returns {<type>} <return value description>`
  * For object or tuple return values, include descriptions for each member.
  * If additional details are needed for each member, please use `:`.

    ```ts
    type ReturnValue = [Object, () => void];

    /**
     * @returns {[Object, () => void]} A tuple containing:
     * - obj `Object` - An object containing:
     *   : label `string` - The label of the input.
     *   : value `string` - The value of the input.
     * - onChange `() => void` - A function to update the value.
     */
    ```

    This JSDoc will be converted into the following documentation.

    Object-type return values can be written in a similar way.

    ```ts
    type ReturnValue = { value: string; onChange: () => void };

    /**
     * @returns {Object} An object containing:
     * - value `string` - The value of the input.
     * - onChange `() => void` - A function to update the value.
     */
    ```

    This JSDoc will be converted into the following documentation.

:::

### Writing Test Code

All implementations must include test code, written with the same name as the implementation. Test coverage must always reach 100%. Use the following command to verify coverage:

```bash
yarn test:coverage
```

::: details Please verify safe operation in SSR environments
All `react-simplikit` implementations use special rendering functions to verify safe operation in SSR environments.

* Component Testing

  ```tsx
  it('is safe on server side rendering', () => {
    // renderSSR.serverOnly is a method that renders the component in the server environment.
    // In this environment, hooks like useEffect are not executed, and objects like window or document are not available, causing errors.
    renderSSR.serverOnly(() => (
      <Component>
        <div>Test Content</div>
      </Component>
    ));

    expect(screen.getByText('Test Content')).toBeInTheDocument();
  });

  it('should render children correctly', async () => {
    // renderSSR is a method that renders the component in the client environment.
    // However, if the HTML rendered on the server and the HTML rendered on the client are different, hydration mismatch errors will occur.
    await renderSSR(() => (
      <Component>
        <div>Test Content</div>
      </Component>
    ));

    expect(screen.getByText('Test Content')).toBeInTheDocument();
  });

  it('should hydration mismatch error occurred', async () => {
    // This test code will fail due to a hydration mismatch error.
    await renderSSR(() => (
      <Component>
        <div>Test Content</div>
        <div>{Math.random()}</div>
      </Component>
    ));

    expect(screen.getByText('Test Content')).toBeInTheDocument();
  });
  ```

* Hook Testing

  ```ts
  it('is safe on server side rendering', () => {
    // renderHookSSR.serverOnly is a method that renders the hook in the server environment.
    // In this environment, hooks like useEffect are not executed, and objects like window or document are not available, causing errors.
    const result = renderHookSSR.serverOnly(() => useToggle(true));
    const [bool] = result.current;
    expect(bool).toBe(true);
  });

  it('should initialize with the default value true', async () => {
    const { result } = await renderHookSSR(() => useToggle(true));
    const [bool] = result.current;
    expect(bool).toBe(true);
  });
  ```

:::

### Creating a Changeset

When your code changes affect the package, you need to create a changeset. Changesets are a tool that automates version management and changelog generation.

#### How to Create a Changeset

1. After implementing your changes, run the following command:

```bash
yarn changeset
```

2. Select the type of change:

   * `patch`: Bug fixes or minor changes
   * `minor`: New features (maintaining backward compatibility)
   * `major`: Breaking changes (breaking backward compatibility)

3. Write a brief summary of your changes.

::: tip
Both packages are currently in the `0.0.x` stage. During this phase, most changes should use `patch`.
If you're unsure about the version type, please discuss with the maintainers.
:::

4. Commit the generated changeset file with your PR.

::: tip
Changeset files are created in the `.changeset` folder and must be committed with your PR. When the PR is merged, the version will be automatically updated and a changelog will be generated.
:::

### Release

When changes are merged into the `main` branch, the release process happens automatically:

1. When a PR is merged into the `main` branch, GitHub Actions will run.
2. If there are changesets, a version update PR will be automatically created.
3. When the version update PR is merged, the new version will be published to npm.

You can view the release results in [GitHub Actions](https://github.com/toss/react-simplikit/actions).

## Documentation Contribution

There are no specific conditions for contributing to documentation. If you find incorrect information, poor translations, or have additional content to add, feel free to make edits. Please write documentation clearly and concisely from the reader's perspective.

## Scaffolding

There's a command that creates the minimum skeleton for contributions. Use the following command to create an implementation folder with a basic structure:

```bash
yarn run scaffold <name> --type <type>
```

* `type`: Implementation type, must be one of `component`, `hook`, or `util`.
* `name`: Name of the implementation.

### Example

```bash
yarn run scaffold Button --type component
```

This command creates three files in the `src/components/Button` folder:

::: code-group

```tsx [Button.tsx]
/**
 * @description
 * <description-here>
 *
 * @param {<param-type>} <param-name> - <param-description>
 * @param {<param-type>} [<param-name>] - <optional-param-description>
 *
 * @returns {<return-type>} <return-description>
 * - <member-description> `<member-name>` - <member-description>
 *
 * @example
 * <example-code>
 */
export function Button() {
  // TODO: Implement Button
}
```

```tsx [Button.spec.ts]
import { describe, expect, it } from 'vitest';

import { renderSSR } from '../../_internal/test-utils/renderSSR.tsx';

import { Button } from './Button.tsx';

describe('Button', () => {
  it('is safe on server side rendering', async () => {
    const result = renderSSR.serverOnly(() => <Button />);
    expect(true).toBe(true);
  });

  it('should work', async () => {
    const result = renderSSR.serverOnly(() => <Button />);
    expect(true).toBe(true);
  });
});
```

```ts [index.ts]
export { Button } from './Button.tsx';
```

:::

::: tip
You can also use these shortcuts:

```bash
yarn run scaffold Button --t c // Create component
yarn run scaffold useButton --t h // Create hook
yarn run scaffold getButton --t u // Create util
```

:::

---

---
url: https://react-simplikit.slash.page/mobile/contributing.md
---
# Contributing to the Mobile Utilities

This guide extends the [core contributing guide](/core/contributing).

## Package Scope

The mobile utilities in `react-simplikit` focus on **solving problems encountered in mobile web environments**.

This includes:

* Viewport management (visual viewport, safe area)
* Keyboard handling (avoiding keyboard-hidden content)
* Layout issues specific to iOS Safari and Android Chrome
* Scroll behavior in mobile browsers

This package is **not** for all browser API-dependent utilities. A hook that uses browser APIs but solves a desktop or general-purpose concern (e.g., keyboard shortcuts, mouse coordinates) does not belong here.

## Development Workflow

```
Scaffold → Implementation → Testing → Documentation → Review → Changeset → Merge
```

### 1. Scaffold

Create the basic structure for a new hook:

```bash
yarn scaffold useNewHook --type h   # Hook
```

### 2. Implementation

Follow the [Design Principles](/mobile/design-principles):

* Named exports only
* Maximize TypeScript inference
* Apply the SSR safety pattern

```typescript
// ✅ SSR-safe pattern
const isClient = typeof window !== 'undefined';
if (!isClient) return defaultValue;
```

### 3. Documentation

All exported functions must include JSDoc with 4 required tags:

```typescript
/**
 * @description One-line summary. (required)
 * @param {Type} name - Description. (required if has params)
 * @returns {Type} Description. (required if has return)
 * @example
 * const result = useHook(input); // (required)
 */
```

::: tip
**Do I need to write documentation?**

No, you don't need to write documentation separately. Instead, please write detailed JSDoc comments, then run `yarn docs:gen <name>` to generate the English documentation from them and commit the result with your PR. Translations are maintained separately; until one exists, the page is shown in English with a notice.
:::

### 4. Testing

100% coverage is required:

```bash
yarn test:spec      # Run single test
yarn test:coverage  # Check coverage
```

#### SSR Testing (Required)

```typescript
it('is safe on server side rendering', () => {
  const result = renderHookSSR.serverOnly(() => useHook());
  expect(result.current).toBeDefined();
});
```

#### Coverage Checklist

* \[ ] All if/else branches
* \[ ] All switch cases
* \[ ] All early returns
* \[ ] Cleanup functions (useEffect return)

### 5. Creating a Changeset

When your code changes affect the package, you need to create a changeset:

```bash
yarn changeset
```

Select the type of change:

* `patch`: Bug fixes or minor changes
* `minor`: New features (maintaining backward compatibility)
* `major`: Breaking changes (breaking backward compatibility)

::: tip
Both packages are currently in the `0.0.x` stage. During this phase, most changes should use `patch`.
If you're unsure about the version type, please discuss with the maintainers.
:::

## Mobile-Specific Guidelines

### Testing on Real Devices

* Testing on iOS Safari and Android Chrome is recommended
* Visual Viewport API behavior should be verified on real devices

### Platform Differences

Consider these platform differences when implementing:

| Feature                    | iOS                                    | Android             |
| -------------------------- | -------------------------------------- | ------------------- |
| `visualViewport.offsetTop` | Becomes negative when keyboard appears | Typically remains 0 |
| Keyboard behavior          | Viewport is pushed up                  | Resizes the layout  |

### window/document Access Pattern

Always use the SSR-safe pattern when accessing browser APIs:

```typescript
// ✅ SSR-safe pattern
const isClient = typeof window !== 'undefined';
if (!isClient) return defaultValue;

// Now safe to use window/document
window.visualViewport?.addEventListener('resize', handler);
```

## Documentation Contribution

There are no specific conditions for contributing to documentation. If you find incorrect information, poor translations, or have additional content to add, feel free to make edits. Please write documentation clearly and concisely from the reader's perspective.

---

---
url: https://react-simplikit.slash.page/core/design-principles.md
---
# Design Principles

`react-simplikit` is designed to be lightweight, reliable, and easy to use. The following principles serve as the core values supporting this design.

## Respect React's Lifecycle Without Interference

`react-simplikit` does not include implementations that directly interfere with React's lifecycle.
For example, it doesn't provide hooks like `useMount` or `useLifecycles`, instead favoring approaches that respect and utilize React's default behaviors.

## Lightweight and Fast Through Zero Dependencies

`react-simplikit` has absolutely no dependencies. By not relying on additional libraries, it minimizes bundle size when integrated into projects and eliminates concerns about performance degradation.

## Ensures Reliability Through 100% Test Coverage

`react-simplikit` thoroughly tests every function and branch.
We write comprehensive tests that include not only basic functionality but also SSR environment considerations for each implementation, preventing issues caused by unexpected behavior.
If you're looking for a reliable library, `react-simplikit` will be an excellent choice.

## Comprehensive Documentation for Easy Understanding and Use

`react-simplikit` provides detailed documentation to help users quickly understand and utilize each feature. The documentation includes:

* **JSDoc Comments**: Detailed explanations of each function's behavior, parameters, and return values.
* **Usage Guides**: Clear and easy-to-follow instructions to get started immediately.
* **Practical Examples**: Examples demonstrating how to utilize implementations in real-world scenarios.

While the primary documentation is in English, Korean documentation is also supported, making it accessible to Korean users.

## Type Safe with Full TypeScript Support

`react-simplikit` is built with TypeScript from the ground up. Every hook and utility comes with:

* **Strict Type Definitions**: All parameters, return values, and options are fully typed
* **IntelliSense Support**: Get autocompletion and inline documentation in your IDE
* **Generic Types**: Flexible APIs that preserve your type information
* **No `any` Types**: We avoid escape hatches that compromise type safety

---

---
url: https://react-simplikit.slash.page/mobile/design-principles.md
---
# Design Principles

The mobile utilities follow the core principles of `react-simplikit`, extended for mobile-specific challenges.

## Core Principles

### Respect React's Lifecycle Without Interference

`react-simplikit` does not include implementations that directly interfere with React's lifecycle.
For example, it doesn't provide hooks like `useMount` or `useLifecycles`, instead favoring approaches that respect and utilize React's default behaviors.

### Lightweight and Fast Through Zero Dependencies

`react-simplikit` has absolutely no dependencies. By not relying on additional libraries, it minimizes bundle size when integrated into projects and eliminates concerns about performance degradation.

### Ensures Reliability Through 100% Test Coverage

`react-simplikit` thoroughly tests every function and branch.
We write comprehensive tests that include not only basic functionality but also SSR environment considerations for each implementation, preventing issues caused by unexpected behavior.

### Comprehensive Documentation for Easy Understanding and Use

`react-simplikit` provides detailed documentation to help users quickly understand and utilize each feature. The documentation includes:

* **JSDoc Comments**: Detailed explanations of each function's behavior, parameters, and return values.
* **Usage Guides**: Clear and easy-to-follow instructions to get started immediately.
* **Practical Examples**: Examples demonstrating how to utilize implementations in real-world scenarios.

### Type Safe with Full TypeScript Support

`react-simplikit` is built with TypeScript from the ground up. Every hook and utility comes with:

* **Strict Type Definitions**: All parameters, return values, and options are fully typed
* **IntelliSense Support**: Get autocompletion and inline documentation in your IDE
* **Generic Types**: Flexible APIs that preserve your type information
* **No `any` Types**: We avoid escape hatches that compromise type safety

## API Design Standards

### Hook Return Values

We follow consistent patterns for hook return values:

* **Object**: For state and related values (e.g., `useKeyboardHeight(): { keyboardHeight }`, `useVisualViewport(): { viewport }`)
* **void**: For side-effect only hooks (e.g., `useBodyScrollLock(): void`)

### Parameters

* Required parameters come first, optional parameters last
* Use an options object for 3+ optional parameters

### SSR Safety Pattern

All hooks follow the SSR-safe pattern:

```typescript
// ✅ SSR-safe - All hooks follow this pattern
const isClient = typeof window !== 'undefined';
if (!isClient) return defaultValue;
```

## Mobile-Specific Principles

### Platform-Aware Design

We consider the behavioral differences between iOS and Android in our implementations:

* **Visual Viewport API differences**:
  * iOS: `offsetTop` becomes negative when the keyboard appears
  * Android: `offsetTop` typically remains 0
* **Keyboard height calculation**: Platform-specific handling for accurate measurements

### SSR Safety First

Every hook includes SSR testing to ensure safe server-side rendering:

```typescript
it('is safe on server side rendering', () => {
  const result = renderHookSSR.serverOnly(() => useHook());
  expect(result.current).toBeDefined();
});
```

### Performance Optimization

Mobile environments require special attention to performance:

* **Event throttling/debouncing**: Optimize frequent events like scroll and resize
* **Passive event listeners**: Use passive listeners where applicable
* **React transitions**: Leverage `startTransition` for non-urgent updates

---

---
url: https://react-simplikit.slash.page/mobile/utils/disableBodyScrollLock.md
---
# disableBodyScrollLock

`disableBodyScrollLock` is a utility function that unlocks the body scroll. It restores the scroll locked by `enableBodyScrollLock` and returns to the saved scroll position. Safe to call in SSR environment (no-op on server). Safe to call even if not locked (no-op).

## Interface

```ts
function disableBodyScrollLock(): void;
```

### Parameters

### Return Value

## Example

```tsx
// When modal opens
enableBodyScrollLock();

// When modal closes
disableBodyScrollLock();
```

---

---
url: https://react-simplikit.slash.page/mobile/utils/enableBodyScrollLock.md
---
# enableBodyScrollLock

`enableBodyScrollLock` is a utility function that locks the body scroll. It prevents the body from scrolling by applying fixed positioning. This is useful when opening modals, drawers, or other overlay components. Safe to call in SSR environment (no-op on server). Calling multiple times has no effect until unlocked.

## Interface

```ts
function enableBodyScrollLock(): void;
```

### Parameters

### Return Value

## Example

```tsx
// When modal opens
enableBodyScrollLock();

// When modal closes
disableBodyScrollLock();
```

---

---
url: https://react-simplikit.slash.page/mobile/utils/getKeyboardHeight.md
---
# getKeyboardHeight

`getKeyboardHeight` is a utility function that returns the current on-screen keyboard height in pixels. This function uses the Visual Viewport API to calculate the keyboard height. It assumes a modern environment where Visual Viewport is supported (Safari / WKWebView 14+, Chrome / Android WebView 80+). The keyboard height is computed as: `window.innerHeight - visualViewport.height - visualViewport.offsetTop` The subtraction of `offsetTop` is required to correctly handle iOS behavior where the visual viewport may shift vertically when the keyboard appears.

## Interface

```ts
function getKeyboardHeight(): number;
```

### Parameters

### Return Value

## Example

```tsx
const height = getKeyboardHeight();

if (height > 0) {
  footer.style.paddingBottom = `${height}px`;
}
```

---

---
url: https://react-simplikit.slash.page/mobile/utils/getSafeAreaInset.md
---
# getSafeAreaInset

`getSafeAreaInset` is a utility function that returns all safe area insets in pixels as an object. This function reads the CSS `env(safe-area-inset-*)` values by creating a temporary DOM element and reading its computed style. Safe area insets account for device-specific UI elements: - **top**: Notch, Dynamic Island, or status bar - **bottom**: Home indicator on Face ID devices - **left/right**: Rounded corners in landscape mode Typical values (iPhone with Face ID, portrait mode): - top: 47-59px (notch/Dynamic Island) - bottom: 34px (home indicator) - left/right: 0px

## Interface

```ts
function getSafeAreaInset(): SafeAreaInset;
```

### Parameters

### Return Value

## Example

```tsx
const { top, bottom, left, right } = getSafeAreaInset();

header.style.paddingTop = `${top}px`;
footer.style.paddingBottom = `${bottom}px`;
```

---

---
url: https://react-simplikit.slash.page/core/components/ImpressionArea.md
---
# ImpressionArea

`ImpressionArea` is a component that measures the time a specific DOM element is visible on the screen and executes callbacks when the element enters or exits the viewport. This component uses the `useImpressionRef` hook to track the element's visibility.

## Interface

```ts
function ImpressionArea(
  as: ElementType = 'div',
  rootMargin: string,
  areaThreshold: number,
  timeThreshold: number,
  onImpressionStart: () => void,
  onImpressionEnd: () => void,
  ref: Ref<HTMLElement>,
  children: React.ReactNode,
  className: string
): JSX.Element;
```

### Parameters

### Return Value

## Example

```tsx
function App() {
  return (
    <ImpressionArea
      onImpressionStart={() => console.log('Element entered view')}
      onImpressionEnd={() => console.log('Element exited view')}
      timeThreshold={1000}
      areaThreshold={0.5}
    >
      <div>Track me!</div>
    </ImpressionArea>
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/installation.md
description: How to install react-simplikit
---

# Installation

You can install `react-simplikit` from [npm](https://npmjs.com/package/react-simplikit) using your favorite package manager.

::: code-group

```sh [npm]
npm install react-simplikit
```

```sh [pnpm]
pnpm add react-simplikit
```

```sh [yarn]
yarn add react-simplikit
```

```sh [bun]
bun add react-simplikit
```

:::

---

---
url: https://react-simplikit.slash.page/mobile/installation.md
description: How to install react-simplikit for mobile web
---

# Installation

You can install `react-simplikit` from [npm](https://npmjs.com/package/react-simplikit) using your favorite package manager.

::: code-group

```sh [npm]
npm install react-simplikit
```

```sh [pnpm]
pnpm add react-simplikit
```

```sh [yarn]
yarn add react-simplikit
```

```sh [bun]
bun add react-simplikit
```

:::

## Requirements

* React 18 or higher
* TypeScript 4.7 or higher (recommended)

## Usage

Import hooks directly from the package:

```tsx
import { useKeyboardHeight, useAvoidKeyboard } from 'react-simplikit';
```

All hooks are tree-shakeable, so you only include what you use in your bundle.

---

---
url: https://react-simplikit.slash.page/core/intro.md
---
# Introduction to react-simplikit

How can we build React-based applications more safely and reliably? We defined the answer as 'writing React codes in a React-like way' and the answer really began to take shape through `react-simplikit`.

`react-simplikit` is a lightweight yet powerful library that provides various useful tools in React environments. It is designed to respect React's design principles while improving the React development experience.

## More Intuitive and Familiar Interface

We provide a development experience as similar as possible to using React's declarative API. Write less and do more, more easily.

### Implementing Toggle Functionality

```tsx
function Page() {
  const [isOpen, setOpen] = useState(false); // [!code --]
  // [!code --]
  const toggle = useCallback(() => {
    // [!code --]
    setOpen(isOpen => !isOpen); // [!code --]
  }, []); // [!code --]
  const [isOpen, toggle] = useToggle(false); // [!code ++]

  return (
    <div>
      <p>Bottom Sheet state: {isOpen ? 'opened' : 'closed'}</p>
      <button onClick={toggle}>Toggle</button>
    </div>
  );
}
```

### Rendering Arrays with Specific Separators

\<template #left>

```tsx
// without `react-simplikit`
const texts = ['hello', 'react', 'world'];

function Page() {
  return (
    <>
      {texts.map((text, idx) => (
        <Fragment key={text}>
          <div>{text}</div>
          {idx < texts.length - 1 ? (
            <Border type="padding24" />
          ) : null}
        </Fragment>
      ))}
    </>
  );
}
```

\<template #right>

```tsx
// with `react-simplikit`
const texts = ['hello', 'react', 'world'];

function Page() {
  return (
    <Separated by={<Border type="padding24" />}>
      {texts.map(text => (
        <div key={text}>{text}</div>
      ))}
    </Separated>
  );
}
```

## Minimizing Unintended Behavior and Bugs with Concise Implementation

All implementations in `react-simplikit` contain no hidden logic. If feature combinations or extensions are needed, we provide interfaces that can be injected externally. We also maintain clean code through modern implementation.

This is why using `react-simplikit` can increase your code's stability and reliability.

```tsx
function Page() {
  // useIntersectionObserver provides minimal functionality for detecting intersection,
  // and receives callback and intersection options through external injection
  const ref = useIntersectionObserver<HTMLDivElement>(
    entry => {
      if (entry.isIntersecting) {
        console.log('Element is in view:', entry.target);
      } else {
        console.log('Element is out of view:', entry.target);
      }
    },
    { threshold: 0.5 }
  );

  return <div ref={ref}>Observe me!</div>;
}
```

## High Reliability

`react-simplikit` ensures high reliability by maintaining 100% test coverage for all implementations.

## Ensuring Safe Operation in SSR Environments

With the active adoption of SSR environments, poorly written components or hooks can cause errors in SSR environments or hydration mismatches. `react-simplikit` was designed to minimize these issues and guarantee this through 100% test coverage in SSR environments.

## No Dependencies Beyond React

Compared to react-use, which has [14 dependencies](https://www.npmjs.com/package/react-use?activeTab=dependencies) excluding React and React-DOM, `react-simplikit` has no dependencies other than peer dependencies on React.

## Links

For more information about react-simplikit, please check out the following link:

* [GitHub](https://github.com/toss/react-simplikit)

---

---
url: https://react-simplikit.slash.page/mobile/utils/isAndroid.md
---
# isAndroid

`isAndroid` is a utility function that detects whether the current device is running Android. Notes: - All Android browsers include the token "Android" in the user agent.

## Interface

```ts
function isAndroid(userAgent: string): boolean;
```

### Parameters

### Return Value

## Example

```tsx
if (isAndroid()) {
  // Android-specific code
  enableAndroidOptimizations();
}
```

---

---
url: https://react-simplikit.slash.page/mobile/utils/isIOS.md
---
# isIOS

`isIOS` is a utility function that detects whether the current device is running iOS or iPadOS.

Notes on platform inconsistencies:

* Prior to iPadOS 13, iPads reported their platform as "iPad" (or matched /iPad/ in UA).
* Starting from iPadOS 13, Apple changed the platform string to "MacIntel" to make websites treat iPadOS as desktop-class Safari. However, these devices still expose multi-touch capabilities.

## Interface

```ts
function isIOS(userAgent: string): boolean;
```

### Parameters

### Return Value

## Example

```tsx
if (isIOS()) {
  // iOS-specific code
  enableIOSOptimizations();
}
```

---

---
url: https://react-simplikit.slash.page/mobile/utils/isKeyboardVisible.md
---
# isKeyboardVisible

`isKeyboardVisible` is a utility function that checks whether the on-screen keyboard is currently visible. This function uses `getKeyboardHeight()` internally and returns `true` if the keyboard height is greater than 0.

## Interface

```ts
function isKeyboardVisible(): boolean;
```

### Parameters

### Return Value

## Example

```tsx
if (isKeyboardVisible()) {
  console.log('Keyboard is open');
} else {
  console.log('Keyboard is closed');
}
```

---

---
url: https://react-simplikit.slash.page/mobile/utils/isServer.md
---
# isServer

`isServer` is a utility function that checks if the code is running on the server. It returns `true` in SSR (Server-Side Rendering) environments where `window` is undefined, and `false` in client-side environments.

## Interface

```ts
function isServer(): boolean;
```

### Parameters

### Return Value

## Example

```tsx
if (isServer()) {
  // SSR-safe code
  return null;
}

// Client-only code
window.addEventListener('resize', handleResize);
```

---

---
url: https://react-simplikit.slash.page/core/utils/mergeProps.md
---
# mergeProps

`mergeProps` is a utility function that merges multiple props objects into a single object. It handles merging of `className`, `style`, and `function` properties.

## Interface

```ts
function mergeProps<PropsList>(
  ...props: PropsList
): TupleToIntersection<PropsList>;
```

### Parameters

### Return Value

## Example

```tsx
const mergedProps = mergeProps(
  { className: 'foo', style: { color: 'red' } },
  { className: 'bar', style: { backgroundColor: 'blue' } }
);
console.log(mergedProps); // { className: 'foo bar', style: { color: 'red', backgroundColor: 'blue' } }
```

---

---
url: https://react-simplikit.slash.page/core/utils/mergeRefs.md
---
# mergeRefs

This function takes multiple refs (RefObject or RefCallback) and returns a single ref that updates all provided refs. It's useful when you need to pass multiple refs to a single element.

## Interface

```ts
function mergeRefs<T>(
  ...refs: Array<RefObject<T> | RefCallback<T> | null | undefined>
): RefCallback<T>;
```

### Parameters

### Return Value

## Example

```tsx
forwardRef(function Component(props, parentRef) {
  const myRef = useRef(null);

  return <div ref={mergeRefs(myRef, parentRef)} />;
});
```

---

---
url: https://react-simplikit.slash.page/mobile/intro.md
---
# Mobile Utilities

A collection of React hooks that solve common UI challenges in mobile web environments.

## Why mobile utilities?

Mobile web development comes with unique challenges that don't exist on desktop:

* **Keyboard avoidance**: Fixed bottom elements get hidden when the on-screen keyboard appears
* **Scroll direction detection**: Headers and navigation bars that show/hide based on scroll
* **Network status monitoring**: Adapting content quality based on connection speed
* **Page visibility tracking**: Pausing videos or analytics when the app goes to background
* **Visual viewport changes**: Handling zoom, keyboard, and viewport resize on mobile browsers

`react-simplikit` provides battle-tested mobile hooks to handle these scenarios with minimal configuration.

## Quick Start

```bash
npm install react-simplikit
```

### Button CTA Example

The most common mobile UI pattern - a fixed bottom button that moves above the keyboard:

```tsx
import { useAvoidKeyboard } from 'react-simplikit';

function FixedBottomCTA() {
  const { style } = useAvoidKeyboard();

  return (
    <div
      style={{
        position: 'fixed',
        bottom: 0,
        left: 0,
        right: 0,
        ...style,
      }}
    >
      <button>Submit</button>
    </div>
  );
}
```

### Chat Input Example

A chat interface with an input field that stays above the keyboard:

```tsx
import { useState } from 'react';
import { useAvoidKeyboard } from 'react-simplikit';

function ChatInput() {
  const { style } = useAvoidKeyboard();
  const [message, setMessage] = useState('');

  return (
    <div
      style={{
        position: 'fixed',
        bottom: 0,
        left: 0,
        right: 0,
        display: 'flex',
        gap: '8px',
        padding: '12px',
        ...style,
      }}
    >
      <input
        type="text"
        value={message}
        onChange={e => setMessage(e.target.value)}
        placeholder="Type a message..."
        style={{ flex: 1 }}
      />
      <button>Send</button>
    </div>
  );
}
```

### With Safe Area

For devices with home indicators (like iPhone), you can add a safe area offset:

```tsx
import { useAvoidKeyboard } from 'react-simplikit';

function FixedBottomCTA() {
  const { style } = useAvoidKeyboard({ safeAreaBottom: 34 });

  return (
    <div
      style={{
        position: 'fixed',
        bottom: 0,
        left: 0,
        right: 0,
        ...style,
      }}
    >
      <button>Submit</button>
    </div>
  );
}
```

## Available Hooks

| Hook                                                   | Description                                       |
| ------------------------------------------------------ | ------------------------------------------------- |
| [useAvoidKeyboard](/mobile/hooks/useAvoidKeyboard)     | Moves fixed elements above the on-screen keyboard |
| [useKeyboardHeight](/mobile/hooks/useKeyboardHeight)   | Returns the current keyboard height               |
| [useBodyScrollLock](/mobile/hooks/useBodyScrollLock)   | Locks body scroll for modals and overlays         |
| [useScrollDirection](/mobile/hooks/useScrollDirection) | Detects scroll direction (up/down)                |
| [useNetworkStatus](/mobile/hooks/useNetworkStatus)     | Monitors network connection status                |
| [usePageVisibility](/mobile/hooks/usePageVisibility)   | Tracks page visibility state                      |
| [useVisualViewport](/mobile/hooks/useVisualViewport)   | Provides visual viewport dimensions and offset    |

---

---
url: https://react-simplikit.slash.page/mobile/roadmap.md
---
# Roadmap

Mobile screens are small, and that small space creates a surprising number of UI challenges. Elements get hidden behind on-screen keyboards, safe areas vary by device, and the viewport the user actually sees often differs from what the browser reports. These are not edge cases — they are everyday realities of mobile development.

## The Problem: Unreliable UI on Mobile Screens

On mobile devices, what users see on their screen doesn't always match what developers expect. Here are a few common scenarios:

* **Keyboard covering input fields**: When a user taps on a text input, the on-screen keyboard slides up and can completely obscure the input field or a submit button fixed at the bottom.
* **Safe area inconsistencies**: Devices with notches, rounded corners, or home indicators (like the iPhone's bottom bar) have reserved areas where content shouldn't be placed — but these vary across devices and OS versions.
* **Viewport confusion**: The browser's layout viewport and the actual visible area (the visual viewport) can differ significantly, especially when the keyboard is open or the page is zoomed. Fixed-position elements may end up in unexpected places.

These issues are not specific to any single OS or device. Whether it's iOS Safari, Android Chrome, or any other mobile browser, the underlying challenge is the same: **the visible area is unpredictable, and standard CSS alone can't reliably account for it**.

## Our Approach: Focus on the Visual Viewport

The mobile utilities in `react-simplikit` take a focused approach to solving these problems. Rather than trying to work around browser quirks with brittle hacks, we center our design around the **visual viewport** — the area of the screen that the user can actually see at any given moment.

By building on the [Visual Viewport API](https://developer.mozilla.org/en-US/docs/Web/API/Visual_Viewport_API), we provide hooks that let you:

* **Detect and respond to keyboard appearance** so that fixed-bottom elements move out of the way naturally.
* **Read safe area insets** to properly account for notches, home indicators, and other device-specific reserved areas.
* **Track the real visible area** so your layout decisions are based on what the user actually sees, not what the browser's layout engine assumes.

The goal is simple: **within the visual viewport, UI should render reliably and predictably**.

## Cross-Platform, Cross-Device

We don't want to be limited to a specific OS or device model. Mobile web is inherently cross-platform, and `react-simplikit` embraces that.

Our hooks are designed to work consistently across:

* **iOS and Android** — the two dominant mobile platforms.
* **Various browsers** — Safari, Chrome, Samsung Internet, and more.
* **Different device form factors** — from compact phones to large-screen devices, with or without notches and home indicators.

Where a specific API is unavailable (e.g., `window.visualViewport` in older browsers), we provide safe fallbacks that degrade gracefully without breaking your UI.

## What's Next

We're continuing to expand the set of mobile hooks available in `react-simplikit`, always guided by the same principle: **make mobile UI development predictable and reliable, regardless of device or OS**. If there's a common mobile UI pain point, chances are we're working on a clean, declarative solution for it.

---

---
url: https://react-simplikit.slash.page/core/components/Separated.md
---
# Separated

`Separated` is a component that inserts a specified component between each child element. It is useful for adding separators, spacing, or other repeating elements in lists.

## Interface

```ts
function Separated(children: React.ReactNode, by: React.ReactNode): JSX.Element;
```

### Parameters

### Return Value

## Example

```tsx
function App() {
  return (
    <Separated by={<Border type="padding24" />}>
      {['hello', 'react', 'world'].map(item => (
        <div key={item}>{item}</div>
      ))}
    </Separated>
  );
  // Expected output:
  // <div>hello</div>
  // <Border type="padding24" />
  // <div>react</div>
  // <Border type="padding24" />
  // <div>world</div>
}
```

---

---
url: https://react-simplikit.slash.page/mobile/utils/subscribeKeyboardHeight.md
---
# subscribeKeyboardHeight

`subscribeKeyboardHeight` is a utility function that subscribes to changes in the on-screen keyboard height. The provided callback is invoked whenever the keyboard height may change, including when the keyboard appears, disappears, or changes size. Internally, this function listens to both `resize` and `scroll` events on the Visual Viewport:

* `resize`: triggered when the visual viewport height changes
* `scroll`: triggered when the visual viewport offset changes (important for iOS where the viewport can shift without resizing)

Performance optimizations:

* Throttled by default (16ms, ~60fps) to prevent excessive callback invocations
* Skips callback when height hasn't changed (deduplication)

## Interface

```ts
function subscribeKeyboardHeight(
  options: SubscribeKeyboardHeightOptions
): SubscribeKeyboardHeightResult;
```

### Parameters

### Return Value

## Example

```tsx
const { unsubscribe } = subscribeKeyboardHeight({
  callback: height => {
    footer.style.paddingBottom = `${height}px`;
  },
  immediate: true,
});

// Later, when cleanup is needed
unsubscribe();
```

---

---
url: https://react-simplikit.slash.page/core/components/SwitchCase.md
---
# SwitchCase

`SwitchCase` is a component that allows you to declaratively render components based on a given value, similar to a `switch-case` statement. It is useful when you need to conditionally render different components depending on a specific state.

## Interface

```ts
function SwitchCase(
  value: Case,
  caseBy: Partial<{ [P in StringifiedValue<Case>]: () => ReactElement | null }>,
  defaultComponent: () => ReactElement | null
): ReactElement | null;
```

### Parameters

### Return Value

## Example

```tsx
function App() {
  return (
    <SwitchCase
      value={status}
      // Renders TypeA, TypeB, or TypeC based on the status value.
      caseBy={{
        a: () => <TypeA />,
        b: () => <TypeB />,
        c: () => <TypeC />,
      }}
      // Renders Default when the status value does not match any case.
      defaultComponent={() => <Default />}
    />
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useAsyncEffect.md
---
# useAsyncEffect

`useAsyncEffect` is a React hook for handling asynchronous side effects in React components. It follows the same cleanup pattern as `useEffect` while ensuring async operations are handled safely.

## Interface

```ts
function useAsyncEffect(
  effect: () => Promise<void | (() => void)>,
  deps: DependencyList
): void;
```

### Parameters

### Return Value

This hook does not return anything.

## Example

```tsx
useAsyncEffect(async () => {
  const data = await fetchData();
  setData(data);

  return () => {
    console.log('Cleanup on unmount or dependencies change');
  };
}, [dependencies]);
```

---

---
url: https://react-simplikit.slash.page/mobile/hooks/useAvoidKeyboard.md
---
# useAvoidKeyboard

`useAvoidKeyboard` is a React hook that helps fixed-bottom elements avoid the on-screen keyboard. It returns a CSS style that can be applied to `position: fixed` elements to smoothly move them above the keyboard when it appears.

## Interface

```ts
function useAvoidKeyboard(
  options: UseAvoidKeyboardOptions
): UseAvoidKeyboardResult;
```

### Parameters

### Return Value

## Example

```tsx
function FixedBottomCTA() {
  const { style } = useAvoidKeyboard();

  return (
    <div
      style={{
        position: 'fixed',
        bottom: 0,
        left: 0,
        right: 0,
        ...style,
      }}
    >
      <button>Submit</button>
    </div>
  );
}

// With safe area bottom offset (e.g., for iPhone home indicator)
function FixedBottomCTA() {
  const { style } = useAvoidKeyboard({ safeAreaBottom: 34 });

  return (
    <div
      style={{
        position: 'fixed',
        bottom: 0,
        left: 0,
        right: 0,
        ...style,
      }}
    >
      <button>Submit</button>
    </div>
  );
}
```

---

---
url: https://react-simplikit.slash.page/mobile/hooks/useBodyScrollLock.md
---
# useBodyScrollLock

`useBodyScrollLock` is a React hook that locks body scroll while the component is mounted. It automatically locks on mount and unlocks on unmount. **Note:** For multiple overlapping modals, use a single lock at the parent level.

## Interface

```ts
function useBodyScrollLock(): void;
```

### Parameters

### Return Value

This hook does not return anything.

## Example

```tsx
function Modal() {
  useBodyScrollLock();
  return <div className="modal">Modal content</div>;
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useBooleanState.md
---
# useBooleanState

`useBooleanState` is a React hook that simplifies managing a boolean state. It provides functions to set the state to `true`, set it to `false`, and toggle its value.

## Interface

```ts
function useBooleanState(
  defaultValue: boolean = false
): readonly [
  state: boolean,
  setTrue: () => void,
  setFalse: () => void,
  toggle: () => void,
];
```

### Parameters

### Return Value

## Example

```tsx
const [open, openBottomSheet, closeBottomSheet, toggleBottomSheet] =
  useBooleanState(false);
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useCallbackOncePerRender.md
---
# useCallbackOncePerRender

`useCallbackOncePerRender` is a React hook that ensures a callback function is executed only once, regardless of how many times it's called. This is useful for one-time operations that should not be repeated, even if the component re-renders.

## Interface

```ts
function useCallbackOncePerRender(
  callback: () => void,
  deps: DependencyList
): (...args: any[]) => void;
```

### Parameters

### Return Value

## Example

```tsx
import { useCallbackOncePerRender } from 'react-simplikit';

function Component() {
  const handleOneTimeEvent = useCallbackOncePerRender(() => {
    console.log('This will only run once');
  }, []);

  return <button onClick={handleOneTimeEvent}>Click me</button>;
}

// With dependencies
function TrackingComponent({ userId }: { userId: string }) {
  const trackUserVisit = useCallbackOncePerRender(() => {
    analytics.trackVisit(userId);
  }, [userId]);

  useEffect(() => {
    trackUserVisit();
  }, [trackUserVisit]);

  return <div>User page</div>;
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useConditionalEffect.md
---
# useConditionalEffect

`useConditionalEffect` is a React hook that conditionally executes effects based on a predicate function. This provides more control over when effects run beyond just dependency changes.

## Interface

```ts
function useConditionalEffect(
  effect: EffectCallback,
  deps: DependencyList,
  condition: (prevDeps: T | undefined, currentDeps: T) => boolean
): void;
```

### Parameters

### Return Value

This hook does not return anything.

## Example

```tsx
import { useConditionalEffect } from 'react-simplikit';

function Component() {
  const [count, setCount] = useState(0);

  // Only run effect when count increases
  useConditionalEffect(
    () => {
      console.log(`Count increased to ${count}`);
    },
    [count],
    (prevDeps, currentDeps) => {
      // Only run when count is defined and has increased
      return prevDeps && currentDeps[0] > prevDeps[0];
    }
  );

  return (
    <button onClick={() => setCount(prev => prev + 1)}>
      Increment: {count}
    </button>
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useControlledState.md
---
# useControlledState

`useControlledState` is a React hook that allows you to control both controlled and uncontrolled states. If you pass the state to `value`, it will be a controlled state, and if you pass the state to `defaultValue`, it will be an uncontrolled state. If both `value` and `defaultValue` are passed, `value` will take precedence.

## Interface

```ts
function useControlledState(props: Object): [T, Dispatch<SetStateAction<T>>];
```

### Parameters

### Return Value

## Example

```tsx
type ToggleProps = {
  value?: boolean;
  defaultValue?: boolean;
  onChange?: (value: boolean) => void;
};

function Toggle({ value, defaultValue, onChange }: ToggleProps) {
  const [on, setOn] = useControlledState({
    value,
    defaultValue: defaultValue ?? false,
    onChange,
  });

  return (
    <button onClick={() => setOn(prev => !prev)}>{on ? 'ON' : 'OFF'}</button>
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useCounter.md
---
# useCounter

`useCounter` is a React hook that manages a numeric counter state with increment, decrement, and reset capabilities. Optionally, you can provide minimum and maximum values to constrain the counter's range.

## Interface

```ts
function useCounter(
  initialValue: number = 0,
  options: UseCounterOptions
): UseCounterReturn;
```

### Parameters

### Return Value

## Example

```tsx
import { useCounter } from 'react-simplikit';

function ShoppingCart() {
  const { count, increment, decrement, reset } = useCounter(1, {
    min: 1,
    max: 10,
  });

  return (
    <div>
      <span>Quantity: {count}</span>
      <button type="button" onClick={decrement}>
        -
      </button>
      <button type="button" onClick={increment}>
        +
      </button>
      <button type="button" onClick={reset}>
        Reset
      </button>
    </div>
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useDebounce.md
---
# useDebounce

`useDebounce` is a React hook that returns a debounced version of the provided callback function. It helps optimize event handling by delaying function execution and grouping multiple calls into one.

## Interface

```ts
function useDebounce<F extends (...args: any[]) => unknown>(
  callback: F,
  wait: number,
  options: DebounceOptions
): F & { cancel: () => void };
```

### Parameters

### Return Value

## Example

```tsx
function SearchInput() {
  const [query, setQuery] = useState('');

  const debouncedSearch = useDebounce((value: string) => {
    // Actual API call
    searchAPI(value);
  }, 300);

  return (
    <input
      value={query}
      onChange={e => {
        setQuery(e.target.value);
        debouncedSearch(e.target.value);
      }}
      placeholder="Enter search term"
    />
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useDebouncedCallback.md
---
# useDebouncedCallback

`useDebouncedCallback` is a React hook that returns a debounced version of the provided callback function. It helps optimize event handling by delaying function execution and grouping multiple calls into one. Note that if both 'leading' and 'trailing' are set, the function will be called at both the start and end of the delay period. However, it must be called at least twice within debounceMs interval for this to happen, since one debounced function call cannot trigger the function twice.

## Interface

```ts
function useDebouncedCallback<T>(options: Object): (nextValue: T) => void;
```

### Parameters

### Return Value

## Example

```tsx
import { useDebouncedCallback } from 'react-simplikit';
import { useState } from 'react';

function SearchInput() {
  const [query, setQuery] = useState('');
  const setQueryDebounced = useDebouncedCallback({
    onChange: setQuery,
    timeThreshold: 300,
  });

  return (
    <>
      <input onChange={e => setQueryDebounced(e.target.value)} />
      <p>Searching for: {query}</p>
    </>
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useDoubleClick.md
---
# useDoubleClick

`useDoubleClick` is a React hook that differentiates between single and double click events. It delays the single click callback execution for a specified time, and cancels it if a second click (i.e. a double click) occurs within that time.

## Interface

```ts
function useDoubleClick<E extends HTMLElement>(
  props: Object
): (event: MouseEvent<E>) => void;
```

### Parameters

### Return Value

## Example

```tsx
function GalleryCard() {
  const [selected, setSelected] = useState(false);

  const handleClick = () => setSelected(prev => !prev);
  const handleDoubleClick = () => alert('Zoom in!');

  const handleEvent = useDoubleClick({
    click: handleClick,
    doubleClick: handleDoubleClick,
  });

  return (
    <div onClick={handleEvent}>{selected ? 'Selected' : 'Not selected'}</div>
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useGeolocation.md
---
# useGeolocation

`useGeolocation` is a React hook that retrieves and tracks the user's geographical location. It uses the browser's `Geolocation API` to support both one-time position retrieval and continuous location tracking.

## Interface

```ts
function useGeolocation(options: GeolocationOptions): Object;
```

### Parameters

### Return Value

## Example

```tsx
// Basic usage
const { loading, error, data, getCurrentPosition } = useGeolocation();

// Automatically fetch location when component mounts
const { loading, error, data } = useGeolocation({ mountBehavior: 'get' });

// Location tracking
const { loading, error, data, startTracking, stopTracking, isTracking } =
  useGeolocation();

const handleStartTracking = () => {
  startTracking();
};

const handleStopTracking = () => {
  stopTracking();
};
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useImpressionRef.md
---
# useImpressionRef

`useImpressionRef` is a React hook that measures the time a specific DOM element is visible on the screen and executes callbacks when the element enters or exits the viewport. It uses `IntersectionObserver` and the `Visibility API` to track the element's visibility.

## Interface

```ts
function useImpressionRef(
  options: UseImpressionRefOptions
): (element: Element | null) => void;
```

### Parameters

### Return Value

## Example

```tsx
import { useImpressionRef } from 'react-simplikit';

function Component() {
  const ref = useImpressionRef<HTMLDivElement>({
    onImpressionStart: () => console.log('Element entered view'),
    onImpressionEnd: () => console.log('Element exited view'),
    timeThreshold: 1000,
    areaThreshold: 0.5,
  });

  return <div ref={ref}>Track my visibility!</div>;
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useInputState.md
---
# useInputState

`useInputState` is a React hook that manages an input state with optional value transformation. The returned `onChange` handler works with both `<input>` and `<textarea>` elements.

## Interface

```ts
function useInputState(
  initialValue: string = '',
  transformValue: (value: string) => string = (v: string) => v
): [
  value: string,
  onChange: ChangeEventHandler<HTMLInputElement | HTMLTextAreaElement>,
];
```

### Parameters

### Return Value

## Example

```tsx
function Example() {
  const [value, onChange] = useInputState('');
  return (
    <>
      <input type="text" value={value} onChange={onChange} />
      <textarea value={value} onChange={onChange} />
    </>
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useIntersectionObserver.md
---
# useIntersectionObserver

`useIntersectionObserver` is a React hook that detects whether a specific DOM element is visible on the screen. It uses the `IntersectionObserver` API to execute a callback when the element enters or exits the viewport.

## Interface

```ts
function useIntersectionObserver(
  callback: (entry: IntersectionObserverEntry) => void,
  options: IntersectionObserverInit
): (element: Element | null) => void;
```

### Parameters

### Return Value

## Example

```tsx
import { useIntersectionObserver } from 'react-simplikit';

function Component() {
  const ref = useIntersectionObserver<HTMLDivElement>(
    entry => {
      if (entry.isIntersecting) {
        console.log('Element is in view:', entry.target);
      } else {
        console.log('Element is out of view:', entry.target);
      }
    },
    { threshold: 0.5 }
  );

  return <div ref={ref}>Observe me!</div>;
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useInterval.md
---
# useInterval

`useInterval` is a React hook that executes a function at a specified interval. It is useful for timers, polling data, and other recurring tasks.

## Interface

```ts
function useInterval(
  callback: () => void,
  options: number | { delay: number; enabled?: boolean; immediate?: boolean }
): void;
```

### Parameters

### Return Value

This hook does not return anything.

## Example

```tsx
import { useInterval } from 'react-simplikit';
import { useState } from 'react';

function Timer() {
  const [time, setTime] = useState(0);

  useInterval(() => {
    setTime(prev => prev + 1);
  }, 1000);

  return (
    <div>
      <p>{time} seconds</p>
    </div>
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useIsClient.md
---
# useIsClient

`useIsClient` is a React hook that returns `true` only in the client-side environment. It is primarily used to differentiate between client-side and server-side rendering (SSR). The state is set to `true` only after the component is mounted in the client-side environment.

## Interface

```ts
function useIsClient(): boolean;
```

### Parameters

### Return Value

## Example

```tsx
function ClientSideContent() {
  const isClient = useIsClient();

  if (!isClient) {
    return <div>Loading...</div>; // Rendered on the server side
  }

  return <div>Client-side rendered content</div>; // Rendered on the client side
}

function ClientOnlyMap() {
  const isClient = useIsClient();

  if (!isClient) return null;

  return <div id="map" />;
}

function ClientTheme() {
  const isClient = useIsClient();

  const theme = isClient ? localStorage.getItem('theme') : 'light';

  return <div>Current theme: {theme}</div>;
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useIsomorphicLayoutEffect.md
---
# useIsomorphicLayoutEffect

`useIsomorphicLayoutEffect` is a React hook that provides the behavior of `useLayoutEffect` without triggering warnings during server-side rendering. During SSR, there is no DOM to synchronously measure or mutate, so React warns about using `useLayoutEffect`.

This hook runs synchronously after DOM updates but before paint, making it ideal for:

* Measuring DOM elements after render
* Applying DOM changes before paint
* Preventing UI flashes or layout shifts
* Supporting both client and server environments

## Interface

```ts
function useIsomorphicLayoutEffect(
  effect: React.EffectCallback,
  deps: React.DependencyList
): void;
```

### Parameters

### Return Value

This hook does not return anything.

## Example

```tsx
useIsomorphicLayoutEffect(() => {
  // Code to be executed during the layout phase on the client side
}, [dep1, dep2, ...]);
```

---

---
url: https://react-simplikit.slash.page/mobile/hooks/useKeyboardHeight.md
---
# useKeyboardHeight

`useKeyboardHeight` is a React hook that tracks the on-screen keyboard height. It returns the current keyboard height in pixels, which updates automatically when the keyboard appears, disappears, or changes size.

## Interface

```ts
function useKeyboardHeight(
  options: UseKeyboardHeightOptions
): UseKeyboardHeightResult;
```

### Parameters

### Return Value

## Example

```tsx
function ChatInput() {
  const { keyboardHeight } = useKeyboardHeight();

  return (
    <div style={{ paddingBottom: `${keyboardHeight}px` }}>
      <input type="text" placeholder="Type a message..." />
    </div>
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useList.md
---
# useList

A React hook that manages an array as state. Provides efficient state management and stable action functions.

## Interface

```ts
function useList<T>(initialState?: T[]): UseListReturn<T>;
```

### Parameters

### Return Value

Returns a tuple `[list, actions]`.

## Example

```tsx
import { useList } from 'react-simplikit';

function TodoList() {
  const [todos, actions] = useList<string>(['Buy milk', 'Walk the dog']);

  return (
    <div>
      <ul>
        {todos.map((todo, index) => (
          <li key={index}>
            {todo}
            <button onClick={() => actions.removeAt(index)}>Delete</button>
          </li>
        ))}
      </ul>
      <button onClick={() => actions.push('New todo')}>Add</button>
      <button onClick={() => actions.reset()}>Reset</button>
    </div>
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useLoading.md
---
# useLoading

`useLoading` is a React hook that simplifies managing the loading state of a `Promise`. It provides a state to track whether an asynchronous operation is in progress and a function to handle the loading state automatically.

## Interface

```ts
function useLoading(): [
  loading: boolean,
  startLoading: <T>(promise: Promise<T>) => Promise<T>,
];
```

### Parameters

### Return Value

## Example

```tsx
function ConfirmButton() {
  const [loading, startLoading] = useLoading();

  const handleSubmit = useCallback(async () => {
    try {
      const result = await startLoading(postConfirmation());
      router.push(`/success?id=${result.id}`);
    } catch (error) {
      console.error('Error:', error);
    }
  }, [startLoading]);

  return (
    <button disabled={loading} onClick={handleSubmit}>
      {loading ? 'Loading...' : 'Confirm'}
    </button>
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useLongPress.md
---
# useLongPress

`useLongPress` is a React hook that detects when an element is pressed and held for a specified duration. It handles both mouse and touch events, making it work consistently across desktop and mobile devices.

## Interface

```ts
function useLongPress<E extends HTMLElement>(
  onLongPress: (event: React.MouseEvent<E> | React.TouchEvent<E>) => void,
  options: UseLongPressOptions
): Object;
```

### Parameters

### Return Value

## Example

```tsx
import { useLongPress } from 'react-simplikit';

function ContextMenu() {
  const [menuVisible, setMenuVisible] = useState(false);

  const longPressHandlers = useLongPress(() => setMenuVisible(true), {
    delay: 400,
    onClick: () => console.log('Normal click'),
    onLongPressEnd: () => console.log('Long press completed'),
  });

  return (
    <div>
      <button {...longPressHandlers}>Press and hold</button>
      {menuVisible && <div className="context-menu">Context Menu</div>}
    </div>
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useMap.md
---
# useMap

A React hook that manages a key-value Map as state. Provides efficient state management and stable action functions.

## Interface

```ts
function useMap(initialState: MapOrEntries<K, V>): UseMapReturn<K, V>;
```

### Parameters

### Return Value

## Example

```tsx
const [userMap, actions] = useMap<string, User>([
  ['user1', { name: 'John', age: 30 }],
]);

// Using values from the Map
const user1 = userMap.get('user1');

// Updating the Map
actions.set('user2', { name: 'Jane', age: 25 });
```

---

---
url: https://react-simplikit.slash.page/mobile/hooks/useNetworkStatus.md
---
# useNetworkStatus

`useNetworkStatus` is a React hook that provides access to the Network Information API. It provides raw network connection data. Returns undefined for all properties if the API is not supported (e.g., Safari, Firefox). **Browser Support**: - Chrome/Edge (Android): Full support - Chrome/Edge (Desktop): Partial support (effectiveType, downlink, rtt, saveData) - Firefox: Not supported - Safari: Not supported

## Interface

```ts
function useNetworkStatus(): NetworkStatus;
```

### Parameters

### Return Value

## Example

```tsx
function AdaptiveImage() {
  const { effectiveType, saveData } = useNetworkStatus();

  // Determine quality based on your app's needs
  const useHighQuality = effectiveType === '4g' && !saveData;

  return (
    <img src={useHighQuality ? 'high-res.jpg' : 'low-res.jpg'} alt="Content" />
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useOutsideClickEffect.md
---
# useOutsideClickEffect

`useOutsideClickEffect` is a React hook that triggers a callback when a click event occurs outside the specified container(s). It is useful for closing modals, dropdowns, tooltips, and other UI components when clicking outside.

## Interface

```ts
function useOutsideClickEffect(
  container: HTMLElement | HTMLElement[] | null,
  callback: () => void
): void;
```

### Parameters

### Return Value

This hook does not return anything.

## Example

```tsx
import { useOutsideClickEffect } from 'react-simplikit';
import { useState } from 'react';

function Example() {
  const [wrapperEl, setWrapperEl] = useState<HTMLDivElement | null>(null);

  useOutsideClickEffect(wrapperEl, () => {
    console.log('Outside clicked!');
  });

  return <div ref={setWrapperEl}>Content</div>;
}
```

---

---
url: https://react-simplikit.slash.page/mobile/hooks/usePageVisibility.md
---
# usePageVisibility

`usePageVisibility` is a React hook that detects page visibility changes. It monitors when the user switches tabs or minimizes the browser using the Page Visibility API. Useful for pausing/resuming animations, videos, or background tasks. **SSR Behavior**: Returns `{ isVisible: true, visibilityState: 'visible' }` during server-side rendering.

## Interface

```ts
function usePageVisibility(): PageVisibility;
```

### Parameters

### Return Value

## Example

```tsx
function VideoPlayer() {
  const { isVisible } = usePageVisibility();
  const videoRef = useRef<HTMLVideoElement>(null);

  useEffect(() => {
    if (!videoRef.current) return;

    // Pause video when tab is hidden
    if (!isVisible) {
      videoRef.current.pause();
    }
  }, [isVisible]);

  return <video ref={videoRef} src="video.mp4" />;
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/usePreservedCallback.md
---
# usePreservedCallback

`usePreservedCallback` is a React hook that maintains a stable reference to a callback function while ensuring it always has access to the latest state or props. This prevents unnecessary re-renders and simplifies dependency management when passing callbacks to child components or handling event listeners.

## Interface

```ts
function usePreservedCallback(
  callback: (...args: any[]) => any
): (...args: any[]) => any;
```

### Parameters

### Return Value

## Example

```tsx
import { usePreservedCallback } from 'react-simplikit';
import { useState } from 'react';

function Counter() {
  const [count, setCount] = useState(0);

  const handleClick = usePreservedCallback(() => {
    console.log(`Current count: ${count}`);
    setCount(prev => prev + 1);
  });

  return <button onClick={handleClick}>Click me</button>;
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/usePreservedReference.md
---
# usePreservedReference

`usePreservedReference` is a React hook that helps maintain the reference of a value when it hasn't changed, while ensuring you can safely use the latest state. It prevents unnecessary re-renders while always allowing access to the latest data.

## Interface

```ts
function usePreservedReference<T extends NotNullishValue>(
  value: T,
  areValuesEqual: (a: T, b: T) => boolean
): T;
```

### Parameters

### Return Value

## Example

```tsx
import { usePreservedReference } from 'react-simplikit';
import { useState } from 'react';

function ExampleComponent() {
  const [state, setState] = useState({ key: 'value' });

  const preservedState = usePreservedReference(state);

  return <div>{preservedState.key}</div>;
}

import { usePreservedReference } from 'react-simplikit';
import { useState } from 'react';

function ExampleComponent() {
  const [state, setState] = useState({ key: 'value' });

  const preservedState = usePreservedReference(
    state,
    (a, b) => a.key === b.key
  );

  return <div>{preservedState.key}</div>;
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/usePrevious.md
---
# usePrevious

`usePrevious` is a React hook that returns the previous value of the input state. It preserves the previous value unchanged when re-renders occur without state changes. If the state is an object or requires custom change detection, a `compare` function can be provided. By default, state changes are detected using `prev === next`.

## Interface

```ts
function usePrevious<T>(state: T, compare: (prev: T, next: T) => boolean): T;
```

### Parameters

### Return Value

## Example

```tsx
const [count, setCount] = useState(0);
// initial value of previousCount is `0`
const previousCount = usePrevious(count);
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useRefEffect.md
---
# useRefEffect

`useRefEffect` is a React hook that helps you set a reference to a specific DOM element and execute a callback whenever the element changes. This hook calls a cleanup function whenever the element changes to prevent memory leaks.

## Interface

```ts
function useRefEffect(
  callback: (element: RefElement) => CleanupCallback | void,
  deps: DependencyList
): (element: RefElement | null) => void;
```

### Parameters

### Return Value

## Example

```tsx
import { useRefEffect } from 'react-simplikit';

function Component() {
  const ref = useRefEffect<HTMLDivElement>(element => {
    console.log('Element mounted:', element);

    return () => {
      console.log('Element unmounted:', element);
    };
  }, []);

  return <div ref={ref}>Basic Example</div>;
}
```

---

---
url: https://react-simplikit.slash.page/mobile/hooks/useSafeAreaInset.md
---
# useSafeAreaInset

`useSafeAreaInset` is a React hook that tracks safe area inset changes. It returns the safe area insets that automatically update when the screen orientation changes (e.g., portrait to landscape). Safe area insets account for device-specific UI elements: - **top**: Notch, Dynamic Island, or status bar - **bottom**: Home indicator on Face ID devices - **left/right**: Rounded corners in landscape mode

## Interface

```ts
function useSafeAreaInset(): SafeAreaInset;
```

### Parameters

### Return Value

## Example

```tsx
function MyComponent() {
  const safeArea = useSafeAreaInset();

  return (
    <div
      style={{
        paddingTop: safeArea.top,
        paddingBottom: safeArea.bottom,
        paddingLeft: safeArea.left,
        paddingRight: safeArea.right,
      }}
    >
      Content that respects safe areas
    </div>
  );
}

// Automatically updates when screen rotates
function RotationAwareHeader() {
  const { top, left, right } = useSafeAreaInset();

  return (
    <header
      style={{
        paddingTop: top,
        paddingLeft: left,
        paddingRight: right,
      }}
    >
      Header content
    </header>
  );
}
```

---

---
url: https://react-simplikit.slash.page/mobile/hooks/useScrollDirection.md
---
# useScrollDirection

`useScrollDirection` is a React hook that detects scroll direction. It returns scroll direction (up/down) and current scroll position. Throttled by default (50ms) for performance.

## Interface

```ts
function useScrollDirection(
  options: UseScrollDirectionOptions
): ScrollDirectionState;
```

### Parameters

### Return Value

## Example

```tsx
function Header() {
  const { direction, position } = useScrollDirection();

  // Hide header on scroll down
  const isHidden = direction === 'down' && position > 100;

  return <header className={isHidden ? 'hidden' : 'visible'}>My Header</header>;
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useSet.md
---
# useSet

A React hook that manages a Set as state. Provides efficient state management and stable action functions.

## Interface

```ts
function useSet<T>(
  initialState?: SetOrValues<T>
): [Omit<Set<T>, 'add' | 'clear' | 'delete'>, SetActions<T>];
```

### Parameters

### Return Value

## Example

```tsx
function TagSelector() {
  const [selectedTags, { add, remove, toggle }] = useSet<string>(['react']);

  return (
    <div>
      {['react', 'vue', 'svelte'].map(tag => (
        <button key={tag} onClick={() => toggle(tag)}>
          {selectedTags.has(tag) ? '✓' : ''} {tag}
        </button>
      ))}
    </div>
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useStorageState.md
---
# useStorageState

`useStorageState` is a React that functions like `useState` but persists the state value in browser storage. The value is retained across page reloads and can be shared between tabs when using `localStorage`.

## Interface

```ts
function useStorageState(
  key: string,
  options: Object
): readonly [
  state: Serializable<T> | undefined,
  setState: (value: SetStateAction<Serializable<T> | undefined>) => void,
  refreshState: () => void,
];
```

### Parameters

### Return Value

## Example

```tsx
// Counter with persistent state
import { useStorageState } from 'react-simplikit';

function Counter() {
  const [count, setCount] = useStorageState<number>('counter', {
    defaultValue: 0,
  });

  return (
    <button onClick={() => setCount(prev => prev + 1)}>Count: {count}</button>
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useThrottle.md
---
# useThrottle

`useThrottle` is a React hook that creates a throttled version of a callback function. This is useful for limiting the rate at which a function can be called, such as when handling scroll or resize events.

## Interface

```ts
function useThrottle<F extends (...args: any[]) => any>(
  callback: F,
  wait: number,
  options: { edges?: Array<'leading' | 'trailing'> }
): F & { cancel: () => void };
```

### Parameters

### Return Value

## Example

```tsx
const throttledScroll = useThrottle(
  () => {
    console.log('Scroll event');
  },
  200,
  { edges: ['leading', 'trailing'] }
);

useEffect(() => {
  window.addEventListener('scroll', throttledScroll);
  return () => {
    window.removeEventListener('scroll', throttledScroll);
    throttledScroll.cancel();
  };
}, [throttledScroll]);
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useThrottledCallback.md
---
# useThrottledCallback

`useThrottledCallback` is a React hook that returns a throttled version of the provided callback function. The throttled callback will only be invoked at most once per specified interval.

## Interface

```ts
function useThrottledCallback<T>(options: Object): (nextValue: T) => void;
```

### Parameters

### Return Value

## Example

```tsx
import { useThrottledCallback } from 'react-simplikit';
import { useState } from 'react';

function ScrollPosition() {
  const [scrollTop, setScrollTop] = useState(0);
  const setScrollTopThrottled = useThrottledCallback({
    onChange: setScrollTop,
    timeThreshold: 200,
  });

  return (
    <div onScroll={e => setScrollTopThrottled(e.currentTarget.scrollTop)}>
      <p>Scrolled {scrollTop}px</p>
    </div>
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useTimeout.md
---
# useTimeout

`useTimeout` is a React hook that executes a callback function after a specified delay. It manages `window.setTimeout` in accordance with the React lifecycle, ensuring cleanup on unmount or when dependencies change.

## Interface

```ts
function useTimeout(callback: () => void, delay: number = 0): void;
```

### Parameters

### Return Value

This hook does not return anything.

## Example

```tsx
// Updating a title after a delay
import { useTimeout } from 'react-simplikit';
import { useState } from 'react';

function Example() {
  const [title, setTitle] = useState('');

  useTimeout(() => {
    setTitle('Searching for products...');
  }, 2000);

  useTimeout(() => {
    setTitle('Almost done...');
  }, 4000);

  return <div>{title}</div>;
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useToggle.md
---
# useToggle

`useToggle` is a React hook that simplifies managing a boolean state. It provides a function to toggle the state between `true` and `false`.

## Interface

```ts
function useToggle(
  initialValue: boolean = false
): [state: boolean, toggle: () => void];
```

### Parameters

### Return Value

## Example

```tsx
import { useToggle } from 'react-simplikit';

function Component() {
  const [open, toggle] = useToggle(false);

  return (
    <div>
      <p>Bottom Sheet state: {open ? 'opened' : 'closed'}</p>
      <button onClick={toggle}>Toggle</button>
    </div>
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/hooks/useVisibilityEvent.md
---
# useVisibilityEvent

`useVisibilityEvent` is a React hook that listens to changes in the document's visibility state and triggers a callback.

## Interface

```ts
function useVisibilityEvent(
  callback: (visibilityState: 'visible' | 'hidden') => void,
  options: object
): void;
```

### Parameters

### Return Value

This hook does not return anything.

## Example

```tsx
import { useVisibilityEvent } from 'react-simplikit';

function Component() {
  useVisibilityEvent(visibilityState => {
    console.log(`Document is now ${visibilityState}`);
  });

  return <p>Check the console for visibility changes.</p>;
}
```

---

---
url: https://react-simplikit.slash.page/mobile/hooks/useVisualViewport.md
---
# useVisualViewport

`useVisualViewport` is a React hook that tracks Visual Viewport changes. It returns the actual visible area in mobile WebView, which changes when the keyboard appears or the user zooms/scrolls. **Important:** `viewport` is `null` on SSR or in browsers that don't support Visual Viewport API. Always check for null before accessing viewport properties. **Tip:** If you only need keyboard height, use `useKeyboardHeight()` instead for a simpler API.

## Interface

```ts
function useVisualViewport(): { viewport: VisualViewportState | null };
```

### Parameters

### Return Value

## Example

```tsx
function CustomLayout() {
  const { viewport } = useVisualViewport();

  // Always check for null first
  if (!viewport) {
    return <div>Visual Viewport not supported</div>;
  }

  const { width, height, offsetTop, scale } = viewport;

  // Hide floating UI when user zooms in
  const showFloatingUI = scale <= 1.3;

  return (
    <div style={{ height }}>
      {showFloatingUI && <FloatingButton />}
      Viewport-aware content
    </div>
  );
}
```

---

---
url: https://react-simplikit.slash.page/core/why-react-simplikit-matters.md
---
# Why react-simplikit matters

Among the many React-based libraries, why should you choose `react-simplikit`? Let's explore our core values and understand why using `react-simplikit` is equivalent to writing React in a React-like way.

## Declarative Interface

React components have evolved from class components to function components.

With the introduction of function components and declarative API hooks, we can now [abstract state and lifecycle-related logic](https://legacy.reactjs.org/docs/hooks-intro.html#its-hard-to-reuse-stateful-logic-between-components) that was previously written in a complex way in class components.

However, React components are still complex. Since React [provides minimal interfaces](https://legacy.reactjs.org/docs/design-principles.html#common-abstraction), components with even slightly complex functionality may require dozens of states, handlers, and side effect definitions based on state changes.

At some point, components become mixed with concerns and are written imperatively, making it increasingly difficult to understand what the component doing and what logic is running.

`react-simplikit` provides appropriate abstractions for frequently used but complex-to-implement features. This allows you to maintain intuitive readability even when writing components with complex logic.

`react-simplikit` presents interfaces that declaratively solve various problems commonly encountered during actual service development.

Based on this, it guides developers to write more declarative React components.

::: code-group

```tsx [without-react-simplikit.tsx]
function AutoCompleteInput() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState<SearchResult[]>([]);
  const [isLoading, setLoading] = useState(false);
  const [isOpen, setOpen] = useState(false);
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const handleClickOutside = (e: MouseEvent) => {
      if (
        containerRef.current &&
        !containerRef.current.contains(e.target as Node)
      ) {
        setOpen(false);
      }
    };

    document.addEventListener('click', handleClickOutside);
    return () => document.removeEventListener('click', handleClickOutside);
  }, []);

  useEffect(() => {
    if (query.trim().length === 0) {
      setResults([]);
      return;
    }

    setLoading(true);
    const timeoutId = setTimeout(async () => {
      try {
        const response = await fetch(`/api/search?q=${query}`);
        const data = await response.json();
        setResults(data);
      } catch (error) {
        console.error('Failed to fetch results:', error);
      } finally {
        setLoading(false);
      }
    }, 300);

    return () => clearTimeout(timeoutId);
  }, [query]);

  return (
    <div ref={containerRef} className="relative">
      <input
        type="text"
        value={query}
        onChange={e => {
          setQuery(e.target.value);
          setOpen(true);
        }}
        onFocus={() => setOpen(true)}
        placeholder="Enter search term"
      />
      {isOpen && (isLoading || results.length > 0) && (
        <div>
          {isLoading ? (
            <div className="p-2">Searching...</div>
          ) : (
            results.map((result, idx) => (
              <Fragment key={result.id}>
                <div
                  onClick={() => {
                    setQuery(result.title);
                    setOpen(false);
                  }}
                >
                  {result.title}
                </div>
                {idx !== results.length - 1 && <Divider />}
              </Fragment>
            ))
          )}
        </div>
      )}
    </div>
  );
}
```

```tsx [with-react-simplikit.tsx]
function AutoCompleteInput() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState<SearchResult[]>([]);
  const [isLoading, startLoading] = useLoading();
  const [isOpen, openSearchBox, closeSearchBox] = useBooleanState(false);

  const searchBoxState = useMemo(() => {
    if (!isOpen) return 'CLOSE';

    if (isLoading) return 'LOADING';

    if (results.length > 0) return 'RESULT_EXISTS';

    return 'EMPTY';
  }, [isOpen, isLoading, results]);

  const searchResults = useDebounce(async (searchQuery: string) => {
    if (searchQuery.trim().length === 0) {
      setResults([]);
      return;
    }

    const response = await startLoading(
      fetch(`/api/search?q=${searchQuery}`)
        .then(res => res.json())
        .catch(error => {
          console.error('Failed to fetch results:', error);
          return [];
        })
    );

    setResults(response);
  }, 300);

  const containerRef = useRef<HTMLDivElement>(null);
  useOutsideClickEffect(containerRef.current, () => closeSearchBox());

  return (
    <div ref={containerRef} className="relative">
      <input
        type="text"
        value={query}
        onChange={e => {
          setQuery(e.target.value);
          openSearchBox();
          searchResults(e.target.value);
        }}
        onFocus={openSearchBox}
        placeholder="Enter search term"
      />
      <SwitchCase
        value={searchBoxState}
        caseBy={{
          LOADING: () => <div>Searching...</div>,
          EMPTY: () => <div>No results found.</div>,
          RESULT_EXISTS: () => (
            <Separated by={<Divider />}>
              {results.map(result => (
                <Fragment key={result.id}>
                  <div
                    onClick={() => {
                      setQuery(result.title);
                      closeSearchBox();
                    }}
                  >
                    {result.title}
                  </div>
                </Fragment>
              ))}
            </Separated>
          ),
          CLOSE: () => null,
        }}
      />
    </div>
  );
}
```

:::

## Small Bundle Size

Fast response time is crucial for web services. That's why small bundle size is very important for `react-simplikit`, a library for building web services. `react-simplikit` strives to provide the smallest possible bundle size now and in the future.

Compared to `react-use`, `react-simplikit` has up to about 89% smaller size:

|                                               | react-simplikit                                                   | react-use                                                    | Difference |
| --------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------ | ---------- |
| Unpacked Size                                 | [237 kB](https://www.npmjs.com/package/react-simplikit)           | [454 kB](https://www.npmjs.com/package/react-use)            | -47.8%     |
| Minified Size                                 | [8.7 kB](https://bundlephobia.com/package/react-simplikit@0.0.29) | [78.2 kB](https://bundlephobia.com/package/react-use@17.6.0) | -88.9%     |
| Gzipped Size                                  | [2.9 kB](https://bundlephobia.com/package/react-simplikit@0.0.29) | [22 kB](https://bundlephobia.com/package/react-use@17.6.0)   | -86.9%     |
| Average Size per Function(Minified Size) | 318.2 byte                                                        | 696.3 byte                                                   | -54.3%     |