Using Solid 2

Requirements

PackageRequired
solid-js>=2.0.0 <3
@solidjs/web>=2.0.0 <3
@internationalized/date3.12.3, if you use DatePicker or DateInput

Use a Solid 2 build toolchain: @solidjs/vite-plugin (or another Solid 2 compiler) with jsxImportSource set to @solidjs/web.

Solid 2 JSX

  • Lowercase attributes. Use tabindex, readonly, maxlength, colspan, and for, not tabIndex, readOnly, maxLength, colSpan, or htmlFor. Component props such as readOnly on Field.Root or NumberInput.Root keep their names.
  • class arrays and objects. class accepts Solid 2's array and toggle object forms on every Lever UI part. There is no classList.
  • No on:, attr:, prop:, or use:. Use camelCase handlers such as onClick. For listener options, add the listener from a ref callback.
  • ARIA booleans. A boolean attribute is present or absent, so aria-expanded={false} removes the attribute. Write 'true' or 'false'.
  • Refs. A ref may be an array of callbacks. Lever UI forwards every one.
  • Deferred writes. A signal read right after a write returns the old value until the next flush. In tests, call flush() before asserting.
Code
<Spinner onClick={handle} tabindex={0} class={{ busy: busy() }} />

Composition: render

Parts accept a render prop beside as and asChild. render receives a props function and the part's state accessor. Use one of as, asChild, or render on a part.

Code
<Accordion.Item
  value="a"
  render={(props, state) => <section {...props()} data-open={String(state().expanded)} />}
>
  …
</Accordion.Item>

state is typed unknown. Narrow it before reading a field. Wrapper types that drop the composition props must drop render too: Omit<SwitchRootProps<'label'>, 'as' | 'asChild' | 'render'>.

Part attributes and IDs

Each part has one attribute named after the component and part, whose value is the part's scoped id.

Code
[data-popover-trigger] {
}

Parts that nothing references, such as most roots, get no id. The ids option only sets the IDs of referenced parts. Pass id to the part itself when you need one. Style with the .leverui-<component>__<part> classes.

Overlay stacking

A z-index on overlay content cannot lift it above the page. For Popover, Menu, Select, Combobox, HoverCard, Tooltip, DatePicker, and ColorPicker, set it on the matching .leverui-<component>__positioner. For toasts, set it on .leverui-toast__toaster. The positioner, and the dialog and drawer backdrop, stack at calc(<layer z-index> + var(--layer-index)).

Utilities and types

  • createContext returns Context<Value | null>. null means no provider. The lookup function returns undefined for a loose context.
  • Input's defaultValue accepts what Solid 2's input accepts.
  • Icon's title accepts false, as Solid 2 attributes do.

Server rendering

Use the Vite plugin's start option with ssr: true. The server rendering guide has the setup and the rules for hydration. Solid 2 writes an empty attribute as its bare name: data-disabled, not data-disabled="". Browsers read both the same way.

Testing

  • Call flush() from solid-js after changing a signal and before asserting.

  • Configure testing-library to flush after events:

    Code
    import { configure } from '@testing-library/dom';
    import { flush } from 'solid-js';
    
    configure({
      eventWrapper(dispatch) {
        const result = dispatch();
        flush();
        return result;
      },
    });
    
  • Wait a microtask after rendering before asserting on machine effects, such as measured sizes or focus moves.