createProxy

createProxy builds component families like Show.div or For.ul, and it can be used externally to create your own proxy components. The steps below walk through a Custom Clickable example.

function createProxy<TProxy extends object, TBase extends object = TProxy>(
  base: TBase,
  renderForTag: (tag: any) => React.ForwardRefExoticComponent<any>,
  category: RegistryCategory
): TProxy;

Define props and base behavior#

Start by defining a base component that contains the shared behavior. The proxy reuses this base for every tag.

import { ComponentPropsWithRef, createElement, forwardRef } from "react";
import { createProxy, BaseTypeHelperFn, ProxyType } from "@ilokesto/utilinent";

export type ClickableProps = {
  onClick?: React.MouseEventHandler;
  disabled?: boolean;
  children?: React.ReactNode;
};

type BaseClickableType<X = object> = {
  (props: X & ClickableProps): React.ReactNode;
};

const BaseClickable: BaseClickableType = ({ onClick, disabled, children }) => {
  return (
    <button type="button" onClick={onClick} disabled={disabled}>
      {children}
    </button>
  );
};

Why BaseClickableType<X = object>? The proxy must accept your custom props plus whatever props belong to each tag or registered component. X is the placeholder for those tag props, and X & ClickableProps merges them. The default object keeps the base usable without extra props. Without the generic, variants like Clickable.div would lose native props such as className, href, or role at the type level.

Add renderForTag + ProxyType#

Provide a tag renderer and declare the proxy type so tag variants like Clickable.div are typed.

const renderForTag =
  (tag: any) =>
  forwardRef(function Render(
    { onClick, disabled, children, ...props }: ClickableProps & ComponentPropsWithRef<any>,
    ref: any
  ) {
    return createElement(
      tag,
      { ...props, ref, onClick, "aria-disabled": disabled ? true : undefined },
      children
    );
  });

interface BaseClickableFn extends BaseTypeHelperFn {
  type: BaseClickableType<this["props"]>;
}

export type ClickableType = ProxyType<BaseClickableFn, "clickable">;

export const Clickable: ClickableType = createProxy(BaseClickable, renderForTag, "clickable");

Why BaseClickableFn extends BaseTypeHelperFn and this["props"]? ProxyType treats BaseTypeHelperFn as a type-level function. It injects each tag's props into the props slot, then evaluates type to produce the final call signature. Using this["props"] makes the signature depend on the tag, so Clickable.div gets ComponentPropsWithRef<"div"> merged with ClickableProps, while Clickable.Link picks up registered component props. If you hardcode ClickableProps here, the tag-specific props will not flow through.

Register custom components (optional)#

import { PluginManager } from "@ilokesto/utilinent";
import Link from "./Link";

PluginManager.register({
  clickable: {
    Link,
  },
});

declare module "@ilokesto/utilinent" {
  interface UtilinentRegister {
    clickable: {
      Link: typeof Link;
    };
  }
}

Usage examples#

Use the default component or tag/component variants once registered.

<Clickable onClick={() => console.log("click")}>Default button</Clickable>
<Clickable.div onClick={() => console.log("click")}>Div wrapper</Clickable.div>
<Clickable.Link href="/docs">Custom Link</Clickable.Link>