// https://github.com/mui/base-ui/blob/1a2ca3c9f8a39bd8c0dda939a7a23b72da226124/packages/react/src/separator/Separator.tsx#L37-L42
export interface SeparatorState {
  /**
   * The orientation of the separator.
   */
  orientation: Orientation;
}

The thing about this feature is that usually, one doesn't expect a component's className to be of type string | undefined | ((state: State) => string | undefined) or its style to be React.CSSProperties | undefined | ((state: State) => React.CSSProperties | undefined). This can cause TypeScript errors or unexpected behavior if consumers of a component use a function unplanned.

For example, in the popular design system shadcn/ui, a common pattern is adding a utility function cn to merge multiple className values.¹

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export const cn = (...inputs: ClassValue[]) => {
  return twMerge(clsx(inputs));
};

Suppose you had an <Input> component like the following (similar to shadcn/ui's <Input> component but shortened for brevity):

import { Input as InputPrimitive } from "@base-ui/react/input";
import type { ComponentProps } from "react";
import { cn } from "../utils/cn";

export const Input = ({
  className,
  ...props
}: ComponentProps<typeof InputPrimitive>) => {
  return (
    <InputPrimitive
      {...props}
      className={cn(
        "flex h-9 w-full appearance-none rounded border border-gray-300 bg-white py-1 text-start dark:border-gray-700 dark:bg-gray-950",
        className,
      )}
    />
  );
};

And then you attempted to use the aforementioned feature by passing a callback function to its className prop:

<Input className={(state) => (state.dirty ? "border-red-600" : undefined)} />

...you would probably notice two strange things:

1. The function is completely ignored
2. There is no TypeScript error despite passing a function for a className

An aside on TypeScript

This is how ClassValue from clsx is defined in TypeScript:

// https://github.com/lukeed/clsx/blob/925494cf31bcd97d3337aacd34e659e80cae7fe2/clsx.d.mts#L1-L3
export type ClassValue =
  | ClassArray
  | ClassDictionary
  | string
  | number
  | bigint
  | null
  | boolean
  | undefined;
export type ClassDictionary = Record<string, any>;
export type ClassArray = ClassValue[];

The most curious option in ClassValue is the ClassDictionary type, which is Record<string, any>.

In TypeScript, Record<string, any> behaves differently compared to other types with an index signature. Typically, if you attempt to assign a function to something with an index signature, you'll get an error like this:

// Type '() => void' is not assignable to type 'Record<string, unknown>'.
//   Index signature for type 'string' is missing in type '() => void'.
const foo: Record<string, unknown> = () => {};

However, for Record<string, any>, this is not checked, so effectively, the type accepts any object, including functions.

This issue was raised in the TypeScript GitHub (microsoft/TypeScript#41746), where @RyanCavanaugh confirms this is intentional behavior.²

An aside on clsx

To make a long story short, on all inputs (including the elements of arrays), clsx returns a string value using toVal. Since typeof className === "function", it simply returns an empty string.

Solution

While this is all fine for shadcn/ui users, there are other times when this type can become problematic. For example, if you use tailwind-variants, you'll get a TypeScript error when passing className directly:

import { Input as InputPrimitive } from "@base-ui/react/input";
import type { ComponentProps } from "react";
import { tv } from "tailwind-variants";

const inputVariants = tv({
  base: "",
});

export const Input = ({
  className,
  ...props
}: ComponentProps<typeof InputPrimitive>) => {
  // Type 'string | ((state: InputState) => string | undefined) | undefined' is not assignable to type 'ClassNameValue'.
  //   Type '(state: InputState) => string | undefined' is not assignable to type 'ClassNameValue'.ts(2322)
  return <InputPrimitive {...props} className={inputVariants({ className })} />;
};

composeRenderProps

In another React UI library, React Aria by Adobe, this concern was solved with the helper function composeRenderProps. I'll be referring to it by that name for consistency; although, given Base UI conventions, it probably should be called something like composeState or composeBaseUiState.

// https://github.com/adobe/react-spectrum/blob/d038f46152341b0afb15b191f34a4b60a074d7a8/packages/react-aria-components/src/utils.tsx#L284-L294
/**
 * A helper function that accepts a user-provided render prop value (either a static value or a
 * function), and combines it with another value to create a final result.
 */
export function composeRenderProps<T, U, V extends T>(
  // https://stackoverflow.com/questions/60898079/typescript-type-t-or-function-t-usage
  value: T extends any ? T | ((renderProps: U) => V) : never,
  wrap: (prevValue: T, renderProps: U) => V,
): (renderProps: U) => V {
  return (renderProps) =>
    wrap(typeof value === "function" ? value(renderProps) : value, renderProps);
}

By using this function, we can correctly handle function className values and avoid TypeScript errors:

<InputPrimitive
  {...props}
  className={composeRenderProps(props.className, (className) =>
    inputVariants({ size, className }),
  )}
/>

Closing thoughts

I honestly find it a bit strange that, as far as I know, this bug hasn't been noticed by any shadcn/ui users despite the library being so popular. The closest documented issue I have found on this is here: shadcn-ui/ui#11303.

While there is a mergeProps helper in Base UI, per documentation,³ it only works with string className values. You can see this is true in the source code. I think it would be very useful if Base UI were to either add a function similar to composeRenderProps or somehow add that functionality to mergeProps.

Using composeRenderProps honestly often makes the code very verbose, but it also opens up some possibilities in terms of styling. For example, one can treat the State as a variant, and style it accordingly with tailwind-variants:

import type { ComponentProps } from "react";
import { Separator as SeparatorPrimitive } from "@base-ui/react/separator";
import { tv } from "tailwind-variants";

import { composeRenderProps } from "../utils/composeRenderProps";

const separatorVariants = tv({
  base: null,
  variants: {
    orientation: {
      horizontal: "h-px border-t",
      vertical: "w-px border-s",
    },
  },
  defaultVariants: { orientation: "horizontal" },
});

export const Separator = ({
  variant,
  size,
  ...props
}: ComponentProps<typeof SeparatorPrimitive>) => {
  return (
    <SeparatorPrimitive
      {...props}
      className={composeRenderProps(props.className, (className, state) =>
        separatorVariants({ className, ...state }),
      )}
    />
  );
};

There are, of course, other use cases, but that is the most obvious to me.

Another minor caveat is that if you are using React Server Components, a function on the server that isn't a server action cannot be passed as a prop to a client component. However, if you accidentally do that, React will notify you with an error, so I don't expect this to be a real concern.

Furthermore, some people like to destructure className from their props. While you can do this without runtime errors, it does result in a bit of a codesmell since there are now two variables named className (the destructured prop and the one provided in the callback). Since the callback className has higher priority within its scope, this won't result in any actual errors in runtime, but it's probably best practice to simply pass it as props.className for clarity.

As Homebrew itself has noted, casks, which use prebuilt binaries from an upstream source, have a different security model compared to formulae built by Homebrew. At the very least, enabling --require-sha will guarantee that the downloaded cask has not changed since it was last reviewed by a Homebrew maintainer.³

The thing is: many Homebrew casks do not have a SHA-256 checksum because their download link is not versionable.⁴ The top ten casks in Homebrew/homebrew-cask that have "no_check" set for their SHA-256 according to their JSON analytics data as of August 7, 2026 are the following:⁵

For more information on this concern, see the following issue on GitHub: Homebrew/homebrew-cask#147305. Hence, enabling --require-sha with any of the above casks installed will lead to this error:⁶

...
==> Verifying checksum for '89947a18e10d5bbda8e2b5d15a60b6823353f019ea1a4b74e3d9c4f91248776e--chromium.rb'
==> Checking cask has checksum
Error: Cask 'chromium' does not have a sha256 checksum defined and was not installed.
This means you have the --require-sha option set, perhaps in your HOMEBREW_CASK_OPTS.
/opt/homebrew/Library/Homebrew/cask/installer.rb:177:in `verify_has_sha'
...

Hopefully, in the future, a feature like pnpm's no-downgrade could be added, where a cask cannot be installed if it now lacks a SHA-256 checksum when it had one previously. A feature such as the aforementioned request for a per-cask option could also prevent this issue.

For now, to quickly enable SHA-256 checksum verification for the casks in your Brewfile that have one available, run the following command:

brew info --cask --quiet --json=v2 $(brew bundle --global list --cask --quiet) | jq --raw-output '
  .casks[]
  | if .sha256 == "no_check" then
      "cask \"\(.token)\" # See Homebrew/homebrew-cask#147305"
    else
      "cask \"\(.token)\", args: { require_sha: true }"
    end
'

This will output the casks portion of the Brewfile (minus pinning, extra arguments, etc.) into stdout and enable require_sha only on the casks that have a SHA-256 checksum.

For me, in React, if I'm expected to handle a Promise, my mind gravitates to either React Query or SWR. My go-to reaction would be to write something like the following:

import { useQuery } from "@tanstack/react-query";

const Component = ({ file }: { file: File }) => {
  const { data: arrayBuffer } = useQuery({
    queryKey: ["Component", file],
    queryFn: () => file.arrayBuffer(),
  });
  // ...
};

The thing is, the part of React Query that is usually the most meaningful for queries is the ability to cache queries, which is done via a queryKey array.² However, since query keys in React Query are serialized into strings using JSON.stringify by default,² your queryKey would end up looking like this: ["Component",{}].

The most straightforward "solution" that usually ensures better caching behavior is to simply use the properties available as a queryKey.

import { useQuery } from "@tanstack/react-query";

const serializeFile = (file: File) => {
  return {
    lastModified: file.lastModified,
    name: file.name,
    webkitRelativePath: file.webkitRelativePath,
    size: file.size,
    type: file.type,
  };
};

const Component = ({ file }: { file: File }) => {
  const { data: arrayBuffer } = useQuery({
    queryKey: ["Component", serializeFile(file)],
    queryFn: () => file.arrayBuffer(),
  });
  // ...
};

However, this really isn't ideal for a couple of reasons. For one, in Blobs, only the size and type properties are available, which really aren't that unique of an identifier. lastModified in Files also just returns the current time by default, so that also may be too unique of an identifier. Furthermore, there are doubtless a number of possible collisions that can occur with this kind of setup.

The solution, it seems, would be to hash the File, somehow, and use that as the queryKey. An algorithm like SHA-256 would be collision-resistant and help prevent doing extra work that was already cached.

While queryKeyHashFn does exist as a property, it seems to only accept synchronous functions.³ The vast majority of hashing functions seem to be asynchronous, including the web default SubtleCrypto.digest, so I suspect this is a non-starter.

My first thought was to simply use useEffect, which compares directly by reference.⁴ Below is a more simplified version of this file.

import { useEffect, useState } from "react";

import { sha256 } from "hash-wasm";

type UseFileHashResult = {
  fileHash: string | null;
  isPending: boolean;
  error: Error | null;
};

export const useFileHash = (
  file: File | undefined | null,
): UseFileHashResult => {
  const [fileHashState, setFileHashState] = useState<UseFileHashResult>(() =>
    !file ?
      { fileHash: null, isPending: false, error: null }
    : { fileHash: null, isPending: true, error: null },
  );

  useEffect(() => {
    if (!file) {
      return;
    }

    const abortController = new AbortController();

    const computeHash = async () => {
      setFileHashState({ fileHash: null, isPending: true, error: null });
      try {
        const fileInBytes = await file.bytes();
        const fileHash = await sha256(fileInBytes);
        if (abortController.signal.aborted) {
          return;
        }
        setFileHashState({ fileHash, isPending: false, error: null });
      } catch (error) {
        if (abortController.signal.aborted) {
          return;
        }
        setFileHashState({
          fileHash: null,
          isPending: false,
          error: error instanceof Error ? error : new Error(String(error)),
        });
      }
    };

    void computeHash();
    return () => abortController.abort();
  }, [file]);

  return fileHashState;
};

In which case, you would use it like this:

import { useQuery } from "@tanstack/react-query";

import { useFileHash } from "./useFileHash";

const Component = ({ file }: { file: File }) => {
  const { fileHash } = useFileHash(file);
  const { data: arrayBuffer } = useQuery({
    queryKey: ["Component", fileHash],
    queryFn: () => file.arrayBuffer(),
    enabled: !!fileHash,
  });

  return <div>{arrayBuffer ? "Loaded" : "Loading..."}</div>;
};

It works... but I'm not really a fan. I have been mostly using React Query's useSuspsenseQuery where setting enabled is not possible.⁵ Furthermore, the code is a bit too verbose and overengineered for something that should be fairly simple.

Alternatively, I tried using React 19's use hook. Since I wasn't using React Server Components, this meant I had to pass the promise from a parent component.

import { Suspense, use } from "react";

import { useQuery } from "@tanstack/react-query";
import { sha256 } from "hash-wasm";

const Parent = ({ file }: { file: File }) => {
  const fileHashPromise = file
    .bytes()
    .then((fileInBytes) => sha256(fileInBytes));

  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Child file={file} fileHashPromise={fileHashPromise} />
    </Suspense>
  );
};

const Child = ({
  file,
  fileHashPromise,
}: {
  file: File;
  fileHashPromise: Promise<string>;
}) => {
  const fileHash = use(fileHashPromise);
  const { data: arrayBuffer } = useSuspenseQuery({
    queryKey: ["Child", fileHash],
    queryFn: () => file.arrayBuffer(),
  });
  // ...
};

Since I already have Suspense around my components due to using useSuspenseQuery, I thought this approach was better and less intrusive. Still, it is a bit frustrating to have the strange nested structure, especially since it's only dependent on the file prop.

As a quick aside, it does raise the question: why doesn't this work?

const Child = ({ file }: { file: File }) => {
  const fileHash = use(file.bytes().then((fileInBytes) => sha256(fileInBytes)));
  // ...
};

If you were to do something like this, the component would infinitely re-render. More specifically, in the React documentation, it notes that "Promises created in Client Components are recreated on every render.⁶"

So, what if we were to make sure the Promise was stable?

The React documentation references creating a promise cache as a useful option for library authors,⁷ so it seems like a viable pattern.

One concern is that using a regular Map would result in the File not being garbage collected even after you are done with it. However, we can instead use a WeakMap, which avoids this specific problem.⁸

import { use } from "react";

import { useSuspenseQuery } from "@tanstack/react-query";
import { sha256 } from "hash-wasm";

const blobHashPromiseCache = new WeakMap<Blob, Promise<string>>();

const getBlobHashPromise = (blob: Blob) => {
  let blobHashPromise = blobHashPromiseCache.get(blob);
  if (blobHashPromise === undefined) {
    blobHashPromise = blob.bytes().then((blobInBytes) => sha256(blobInBytes));
    blobHashPromiseCache.set(blob, blobHashPromise);
  }
  return blobHashPromise;
};

const Child = ({ file }: { file: File }) => {
  const fileHash = use(getBlobHashPromise(file));
  const { data: arrayBuffer } = useSuspenseQuery({
    queryKey: ["Child", fileHash],
    queryFn: () => file.arrayBuffer(),
  });
  // ...
};

This does seem to work, and it has been what I have been using for my application. Here is my complete useFileHash.tsx (and accompanying unit tests) at the time of writing, if you are curious.

One minor caveat is that you may also want to add the properties .name and .lastModified to your queryKey if those are important to your processing, as this only generates a SHA-256 hash of the file's contents.

I can also foresee other concerns that may be meaningful. For one, getBlobHashPromise is not a pure function, which may lead to unpredictable behavior or bugs. Furthermore, the cache being stored at the module level may have implications or consequences. Nonetheless, for my use case, it has been working well.