arkyn
ChangelogGuides
docs / components / introduction

Introduction to components

@arkyn/components is the React UI layer of Arkyn. It provides ready-to-use components, client-side hooks, context providers, and a few utility helpers that work together to build consistent interfaces with less boilerplate.

Why @arkyn/components?

The library is designed for application teams that want a shared UI foundation without giving up flexibility. It covers common interface patterns such as forms, overlays, feedback, media controls, navigation, and client-only rendering, while keeping the API small and predictable.
Main benefits:
  • Consistent UI primitives: Buttons, inputs, layout helpers, alerts, tooltips, tabs, uploaders, and more.
  • Stateful composition: Hooks like useModal, useDrawer, useToast, and useForm connect UI with shared application state.
  • Context-driven workflows: Providers make modal, drawer, form, and toast behavior available across the tree.
  • SSR-safe patterns: ClientOnly and useHydrated help avoid hydration mismatches in mixed server/client rendering.
  • Reusable rich text helpers: toHtml and toRichTextValue convert between editor models and HTML.

Installation

To start using Arkyn components in your project, install the package along with its required peer dependencies:

bash

bun add @arkyn/components

Dependencies

Some components rely on optional peer dependencies that are only needed if you use them: @react-google-maps/api or mapbox-gl for map components like MapView/SearchPlaces, is-hotkey and slate/slate-history/slate-react for the rich text editor, react-scroll for scroll-based automation (e.g. useAutomation), and react-hot-toast for toast notifications. You don't need to install these unless you use the components that require them, but if you want to avoid runtime errors, you can install all of them at once:

bash

bun add @react-input/mask html-react-parser lucide-react react react-dom react-hot-toast

Configuration

After installing the dependencies, you need to configure your project to use the Arkyn component styles. Follow these steps:

1. Import the styles

In the root file of your application (usually main.tsx, index.tsx, root.tsx or App.tsx), import the component styles:

tsx

import "@arkyn/components/styles";
This aggregate import includes the styles for every component in the library. If you only use a handful of components, you can instead import just the CSS for each one from its matching subpath, e.g. @arkyn/components/button.css:

tsx

import "@arkyn/components/button.css";
import "@arkyn/components/modalContainer.css";
Each per-component stylesheet also includes the styles of any other component it renders internally (for example, modalContainer.css also contains the styles it needs from any components ModalContainer uses under the hood), so you don't need to chase down internal dependencies manually.
Prefer the aggregate @arkyn/components/styles import when you use many components across your app, or when several of the components you use share internals, importing each one's .css file separately in that case can end up duplicating the shared styles. Prefer the per-component .css imports when you only use a small, distinct set of components and want to avoid shipping CSS for the rest of the library.

2. (Optional) Customize CSS variables

Every CSS variable used by the library already ships with a default fallback value, so this step is optional. You only need it if you want to override the default design tokens to match your application's design system. To do so, create a CSS file (e.g., globals.css, app.css or variables.css) and redeclare the variables you want to change:

css

:root {
    --white: #ffffff;


  /* background */
  --background: #f4f4f5;
  --background-underground: #fafafa;
  --background-foreground: #ffffff;


  /* text */
  --text-heading: #09090b;
  --text-body: #52525b;
  --text-muted: #a1a1aa;


  /* border */
  --border: #e2e8f0;


  /* inputs, textarea, select, checkbox, etc. */
  --input-background: #fafafa;


  /* tooltip */
  --tooltip-text: #fafafa;
  --tooltip-background: #27272a;


  /* spotlight */
  --spotlight-primary: 17, 109, 220; /* #116ddc */
  --spotlight-secondary: 100, 116, 139; /* #64748B */
  --spotlight-success: 16, 185, 129; /* #10b981 */
  --spotlight-danger: 244, 63, 94; /* #f43f5e */
  --spotlight-info: 14, 165, 233; /* #0ea5e9 */
  --spotlight-warning: 249, 115, 22; /* #f97316 */


  --spotlight-primary-foreground: 231, 240, 252; /* #E7F0FC */
  --spotlight-secondary-foreground: 250, 250, 250; /* #fafafa */
  --spotlight-success-foreground: 231, 248, 242; /* #E7F8F2 */
  --spotlight-danger-foreground: 254, 236, 239; /* #FEECEF */
  --spotlight-info-foreground: 231, 246, 253; /* #E7F6FD */
  --spotlight-warning-foreground: 254, 241, 232; /* #FEF1E8 */
}
You don't need to redeclare every variable, only the ones you want to override. Any variable you don't set keeps using the library's built-in fallback. If you do create this file, make sure to import it into your application's root file as well.

Library Overview

The documentation is grouped to match how the package is actually used in application code:

Components

Reusable UI building blocks for everyday interfaces, such as Button, Input, Select, Tooltip, Checkbox, Drawer, and ClientOnly.

Hooks

State and behavior hooks that coordinate with the rest of the library, including useModal, useDrawer, useToast, useForm, useHydrated, and useSearchAutomation.

Providers

Context providers that power the hooks and keep state available throughout the tree, such as ModalProvider, DrawerProvider, FormProvider, and ToastProvider.

Rich Text Helpers

Utility functions for editor content conversion, including toHtml and toRichTextValue.

Recommended Setup Order

  1. Install @arkyn/components and its required peer dependencies.
  2. Import the library stylesheet in your app entry file.
  3. (Optional) Override the CSS variables in a global stylesheet to match your design system.
  4. Wrap the parts of your app that need shared state with the matching providers.
  5. Use the hooks and components together to build the UI.

Using with AI coding assistants

@arkyn/components ships its own AGENTS.md file inside the published package (available at node_modules/@arkyn/components/AGENTS.md after install), a reference written specifically for AI coding assistants like Claude Code, Cursor, or Copilot. It documents every component, hook, and provider's exact props, import path, and behavior, so your assistant doesn't need to read the source to use the library correctly.
Run @arkyn/cli once in your project to link it in:

bash

npx @arkyn/cli init --agents
This writes a marked block into your project's AGENTS.md pointing at @arkyn/components' bundled docs (and those of any other installed @arkyn/* package). Rerun it whenever you add or remove Arkyn packages. See the @arkyn/cli introduction for details.

Next steps

After completing the installation and configuration, explore the component, hook, and provider sections to see how the pieces fit together in real application flows.
On this page
    arkyn