Clerk JavaScript SDKs

The @clerk/headless package provides unstyled, accessible React UI primitives. These components handle complex logic such as positioning, keyboard navigation, focus management, and ARIA attributes using Floating UI.

Note: This package is marked as internal (private: true) and is intended to be consumed by @clerk/ui. It is separated from @clerk/ui to avoid JSX transform conflicts between the standard react-jsx required by these primitives and the @emotion/react source used by @clerk/ui.

The Organization Profile Domains Section is a high-level component used to manage an organization's domains. It provides a unified interface for:

• Listing existing domains.
• Adding and verifying new domains via an add/verify wizard.
• Editing the enrollment mode of verified domains.
• Removing domains via a removal confirmation flow.

The component manages its own internal state using three distinct state machines to coordinate the list view, the add/verify wizard, the enrollment editor, and the removal confirmation flows.

The @clerk/localizations package provides localized strings for Clerk components. You can use these strings to provide localization for your users or to override default wording to match your brand's voice.

Note: Clerk officially maintains only the en-US (English - United States) locale. All other language translations in this package are community contributions.

The Menu is a headless primitive from @clerk/headless that provides a floating list of actions triggered by a button. It manages complex logic including:

• Open/closed state
• Portalling to avoid overflow issues
• Floating-UI positioning
• Roving-focus keyboard navigation (including typeahead)
• Submenu coordination
• ARIA wiring

Because it is headless, it ships no styles. You must provide your own CSS by targeting the data-* attributes emitted by each part.

The Popover is a headless primitive from @clerk/headless. It provides the logic for a floating panel anchored to a trigger, including:

• Open state management
• Portalling
• Floating-UI positioning (flip/shift/arrow)
• Focus management
• Dismissal (via outside press or Escape key)
• ARIA wiring

Because it is headless, it ships no styles. You must provide your own CSS by targeting the data-* attributes emitted by each part.

Since Select is headless, you must use the emitted data-* attributes to apply styles.

State Attributes:

• data-open: Present on Trigger and Popup when the dropdown is open.
• data-closed: Present on Trigger and Popup when closed (Note: Popup stays mounted to allow exit animations).
• data-selected: Present on Option for the currently selected item.
• data-active: Present on Option for the item currently highlighted via keyboard.
• data-disabled: Present on Option for disabled items.
• data-starting-style: Present on Popup during the entering frame.
• data-ending-style: Present on Popup during the exit animation.

Positioning Attributes:

• data-side: Present on Positioner and Arrow (values: top, bottom, left, right).

The Appearance object extends the Theme object by adding specific keys for every Clerk component. This allows you to target the styling of a specific component (like signIn or userButton) within a global appearance configuration.

Every Clerk component has a corresponding key in the Appearance object that accepts a Theme object.

Appearance = Theme & {
  signIn?: Theme
  signUp?: Theme
  userButton?: Theme
  userProfile?: Theme
  organizationSwitcher?: Theme
  organizationProfile?: Theme
  // ... every Clerk component has a key
}

The Organization Profile Profile Section is a specialized component designed to manage the lifecycle of editing an organization's identity. It handles the open, editing, and saving states for an organization's name and slug.

Key Features:

• State Management: It manages the UI state for opening a dialog, entering edit mode, and the saving process.
• Drafting Mechanism: Edits are treated as machine-owned drafts. The form seeds itself with current organization values and only commits changes upon a successful save.
• Dialog Integration: It automatically wraps the edit form in a Dialog component.
• Automatic Closure: The component is designed to close the editing dialog automatically once a save operation succeeds, without requiring manual syncing effects.

The FileUpload primitive uses a provider/consumer pattern.

1. FileUpload.Root: Acts as the provider. It owns the file state, the hidden input, and provides the context for all sub-components.
2. FileUpload.useFileUpload(): A hook used inside FileUpload.Root to access the current state and control methods. It returns:
   • files: The current list of selected File objects.
   • addFiles: Method to add files.
   • removeFile: Method to remove a specific file.
   • clearFiles: Method to clear all files.
   • openFilePicker: Method to programmatically open the file picker.
   • disabled: Boolean indicating if the uploader is disabled.
3. Parts: Components like Trigger, Dropzone, and Item consume the context from Root to perform their specific roles (e.g., opening the picker or deleting an item).

To ensure Select.Value can display the correct label during Server-Side Rendering (SSR) or before the actual Select.Option components have mounted, provide an items array to Select.Root.

Note: The items prop is only for label resolution; it does not automatically render the options. You must still manually render the Select.Option children.

const items = [
  { value: 'apple', label: 'Apple' },
  { value: 'banana', label: 'Banana' },
];

<Select.Root
  items={items}
  defaultValue='apple'
>
  {/* Select.Value will display "Apple" even before Options mount */}
</Select.Root>;