@ariakit/react-core 0.3.1 → 0.3.3

package/cjs/popover/popover.cjs

@@ -1,18 +1,18 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
 
-var _PHDU6PLMcjs = require('../__chunks/PHDU6PLM.cjs');
-require('../__chunks/ZEASCR4B.cjs');
-require('../__chunks/J63NAJOO.cjs');
-require('../__chunks/6BAHKJ5K.cjs');
-require('../__chunks/DPLHWKRP.cjs');
+var _WUQKDMC4cjs = require('../__chunks/WUQKDMC4.cjs');
+require('../__chunks/PQU457XU.cjs');
+require('../__chunks/45OYD4CU.cjs');
+require('../__chunks/RWS2MAR2.cjs');
+require('../__chunks/DFFFHQVQ.cjs');
 require('../__chunks/W32FX7DM.cjs');
-require('../__chunks/JKMBJCXA.cjs');
-require('../__chunks/INDMFBTS.cjs');
-require('../__chunks/NBCR3CLP.cjs');
+require('../__chunks/QK4GI6B3.cjs');
+require('../__chunks/COHI5HTS.cjs');
+require('../__chunks/F4RJLWZG.cjs');
 require('../__chunks/56NPFF7P.cjs');
 require('../__chunks/Z3TLXRS7.cjs');
-require('../__chunks/PD5YFDLO.cjs');
+require('../__chunks/TLA46MN6.cjs');
 require('../__chunks/X2GXTE3P.cjs');
 require('../__chunks/VTRMALP6.cjs');
 require('../__chunks/BWQVQDGC.cjs');
@@ -28,16 +28,16 @@ require('../__chunks/5E5FKYEO.cjs');
 require('../__chunks/AKOG5S2T.cjs');
 require('../__chunks/W6ZRSMO5.cjs');
 require('../__chunks/A2NMYLCG.cjs');
-require('../__chunks/BFLDQF3L.cjs');
+require('../__chunks/GQAB4M3B.cjs');
 require('../__chunks/LHHW5ZQP.cjs');
 require('../__chunks/KSFAO77E.cjs');
 require('../__chunks/Z5PUIG6A.cjs');
-require('../__chunks/6MLKTO2T.cjs');
-require('../__chunks/I63PYP2U.cjs');
+require('../__chunks/HRUFFILM.cjs');
+require('../__chunks/UHRHLHM2.cjs');
 require('../__chunks/5WLTMVVQ.cjs');
 require('../__chunks/7WUTS26Y.cjs');
 require('../__chunks/72I2GWXF.cjs');
 
 
 
-exports.Popover = _PHDU6PLMcjs.Popover; exports.usePopover = _PHDU6PLMcjs.usePopover;
+exports.Popover = _WUQKDMC4cjs.Popover; exports.usePopover = _WUQKDMC4cjs.usePopover;

package/cjs/popover/popover.d.ts

@@ -24,16 +24,20 @@ export declare const usePopover: import("../utils/types.js").Hook<PopoverOptions
  * @see https://ariakit.org/components/popover
  * @example
  * ```jsx
- * const popover = usePopoverStore();
- * <PopoverDisclosure store={popover}>Disclosure</PopoverDisclosure>
- * <Popover store={popover}>Popover</Popover>
+ * <PopoverProvider>
+ *   <PopoverDisclosure>Disclosure</PopoverDisclosure>
+ *   <Popover>Popover</Popover>
+ * </PopoverProvider>
  * ```
  */
 export declare const Popover: import("../utils/types.js").Component<PopoverOptions<"div">>;
 export interface PopoverOptions<T extends As = "div"> extends DialogOptions<T> {
     /**
-     * Object returned by the `usePopoverStore` hook.
-     * @see https://ariakit.org/guide/component-stores
+     * Object returned by the
+     * [`usePopoverStore`](https://ariakit.org/reference/use-popover-store) hook.
+     * If not provided, the closest
+     * [`PopoverProvider`](https://ariakit.org/reference/popover-provider)
+     * component's context will be used.
      */
     store?: PopoverStore;
     /**
@@ -59,10 +63,10 @@ export interface PopoverOptions<T extends As = "div"> extends DialogOptions<T> {
     shift?: number;
     /**
      * Controls the behavior of the popover when it overflows the viewport:
-     *   - If a `boolean`, specifies whether the popover should flip to the
-     *     opposite side when it overflows.
-     *   - If a `string`, indicates the preferred fallback placements when it
-     *     overflows. The placements must be spaced-delimited, e.g. "top left".
+     * - If a `boolean`, specifies whether the popover should flip to the opposite
+     *   side when it overflows.
+     * - If a `string`, indicates the preferred fallback placements when it
+     *   overflows. The placements must be spaced-delimited, e.g. "top left".
      * @default true
      */
     flip?: boolean | string;

package/cjs/portal/portal.d.ts

@@ -22,8 +22,9 @@ export declare const Portal: import("../utils/types.js").Component<PortalOptions
 export interface PortalOptions<T extends As = "div"> extends Options<T> {
     /**
      * When enabled, `preserveTabOrder` will keep the DOM element's tab order the
-     * same as the order in which the `Portal` component was mounted in the React
-     * tree.
+     * same as the order in which the underlying
+     * [`Portal`](https://ariakit.org/reference/portal) component was mounted in
+     * the React tree.
      * @default false
      */
     preserveTabOrder?: boolean;
@@ -32,8 +33,11 @@ export interface PortalOptions<T extends As = "div"> extends Options<T> {
      * useful when you need to be informed when the portal element is appended to
      * the DOM or removed from the DOM.
      * @example
+     * ```jsx
      * const [portalElement, setPortalElement] = useState(null);
-     * <Portal portalRef={setPortalElement} />;
+     *
+     * <Portal portalRef={setPortalElement} />
+     * ```
      */
     portalRef?: RefCallback<HTMLElement> | MutableRefObject<HTMLElement | null>;
     /**
@@ -47,17 +51,24 @@ export interface PortalOptions<T extends As = "div"> extends Options<T> {
      * will be a `div` element appended to the `document.body`.
      * @default HTMLDivElement
      * @example
+     * ```jsx
      * const [portal, setPortal] = useState(null);
-     * <Portal portalElement={portal} />;
-     * <div ref={setPortal} />;
+     * <>
+     *   <Portal portalElement={portal} />
+     *   <div ref={setPortal} />
+     * </>
+     * ```
      * @example
+     * ```jsx
      * const getPortalElement = useCallback(() => {
      *   const div = document.createElement("div");
      *   const portalRoot = document.getElementById("portal-root");
      *   portalRoot.appendChild(div);
      *   return div;
      * }, []);
-     * <Portal portalElement={getPortalElement} />;
+     *
+     * <Portal portalElement={getPortalElement} />
+     * ```
      */
     portalElement?: ((element: HTMLElement) => HTMLElement | null) | HTMLElement | null;
 }

package/cjs/radio/radio-group.cjs

@@ -4,11 +4,11 @@
 var _FPNO6JL5cjs = require('../__chunks/FPNO6JL5.cjs');
 
 
-var _6G5GJF5Qcjs = require('../__chunks/6G5GJF5Q.cjs');
+var _SELCJFCBcjs = require('../__chunks/SELCJFCB.cjs');
 require('../__chunks/KLZID3QO.cjs');
 require('../__chunks/H7R5D2FR.cjs');
 require('../__chunks/NHZBX2RS.cjs');
-require('../__chunks/BFLDQF3L.cjs');
+require('../__chunks/GQAB4M3B.cjs');
 require('../__chunks/LHHW5ZQP.cjs');
 
 
@@ -44,7 +44,7 @@ var useRadioGroup = _Z5PUIG6Acjs.createHook.call(void 0,
     props = _72I2GWXFcjs.__spreadValues.call(void 0, {
       role: "radiogroup"
     }, props);
-    props = _6G5GJF5Qcjs.useComposite.call(void 0, _72I2GWXFcjs.__spreadValues.call(void 0, { store }, props));
+    props = _SELCJFCBcjs.useComposite.call(void 0, _72I2GWXFcjs.__spreadValues.call(void 0, { store }, props));
     return props;
   }
 );

package/cjs/radio/radio-group.d.ts

@@ -30,7 +30,11 @@ export declare const useRadioGroup: import("../utils/types.js").Hook<RadioGroupO
 export declare const RadioGroup: import("../utils/types.js").Component<RadioGroupOptions<"div">>;
 export interface RadioGroupOptions<T extends As = "div"> extends CompositeOptions<T> {
     /**
-     * Object returned by the `useRadioStore` hook.
+     * Object returned by the
+     * [`useRadioStore`](https://ariakit.org/reference/use-radio-store) hook. If
+     * not provided, the closest
+     * [`RadioProvider`](https://ariakit.org/reference/radio-provider) component's
+     * context will be used.
      */
     store?: RadioStore;
 }

package/cjs/radio/radio-provider.cjs

@@ -1,15 +1,15 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-var _EQEXTQQ6cjs = require('../__chunks/EQEXTQQ6.cjs');
+var _6G334OGZcjs = require('../__chunks/6G334OGZ.cjs');
 
 
 var _FPNO6JL5cjs = require('../__chunks/FPNO6JL5.cjs');
-require('../__chunks/FWCQCCG3.cjs');
-require('../__chunks/GCTYF2Y6.cjs');
+require('../__chunks/JDIVO6OK.cjs');
+require('../__chunks/K5M7LOPE.cjs');
 require('../__chunks/H7R5D2FR.cjs');
 require('../__chunks/NHZBX2RS.cjs');
 require('../__chunks/Z5PUIG6A.cjs');
-require('../__chunks/I63PYP2U.cjs');
+require('../__chunks/UHRHLHM2.cjs');
 require('../__chunks/5WLTMVVQ.cjs');
 require('../__chunks/7WUTS26Y.cjs');
 require('../__chunks/72I2GWXF.cjs');
@@ -17,7 +17,7 @@ require('../__chunks/72I2GWXF.cjs');
 // src/radio/radio-provider.tsx
 var _jsxruntime = require('react/jsx-runtime');
 function RadioProvider(props = {}) {
-  const store = _EQEXTQQ6cjs.useRadioStore.call(void 0, props);
+  const store = _6G334OGZcjs.useRadioStore.call(void 0, props);
   return /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _FPNO6JL5cjs.RadioContextProvider, { value: store, children: props.children });
 }
 

package/cjs/radio/radio-store.cjs

@@ -1,14 +1,14 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
 
-var _EQEXTQQ6cjs = require('../__chunks/EQEXTQQ6.cjs');
-require('../__chunks/FWCQCCG3.cjs');
-require('../__chunks/GCTYF2Y6.cjs');
-require('../__chunks/I63PYP2U.cjs');
+var _6G334OGZcjs = require('../__chunks/6G334OGZ.cjs');
+require('../__chunks/JDIVO6OK.cjs');
+require('../__chunks/K5M7LOPE.cjs');
+require('../__chunks/UHRHLHM2.cjs');
 require('../__chunks/5WLTMVVQ.cjs');
 require('../__chunks/7WUTS26Y.cjs');
 require('../__chunks/72I2GWXF.cjs');
 
 
 
-exports.useRadioStore = _EQEXTQQ6cjs.useRadioStore; exports.useRadioStoreProps = _EQEXTQQ6cjs.useRadioStoreProps;
+exports.useRadioStore = _6G334OGZcjs.useRadioStore; exports.useRadioStoreProps = _6G334OGZcjs.useRadioStoreProps;

package/cjs/radio/radio-store.d.ts

@@ -22,11 +22,6 @@ export interface RadioStoreFunctions extends Core.RadioStoreFunctions, Composite
 export interface RadioStoreOptions extends Core.RadioStoreOptions, CompositeStoreOptions {
     /**
      * Function that will be called when the `value` state changes.
-     * @param value The new value.
-     * @example
-     * function RadioGroup({ value, onChange }) {
-     *   const radio = useRadioStore({ value, setValue: onChange });
-     * }
      */
     setValue?: (value: RadioStoreState["value"]) => void;
 }

package/cjs/radio/radio.cjs

@@ -1,22 +1,22 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
 
-var _ZJ4ICN62cjs = require('../__chunks/ZJ4ICN62.cjs');
+var _L4TB7MRWcjs = require('../__chunks/L4TB7MRW.cjs');
 require('../__chunks/FPNO6JL5.cjs');
-require('../__chunks/G33PRHOG.cjs');
-require('../__chunks/NPDPNCSD.cjs');
+require('../__chunks/D3SPQ2OY.cjs');
+require('../__chunks/FXRXBA2Y.cjs');
 require('../__chunks/FMI5QF7N.cjs');
 require('../__chunks/KLZID3QO.cjs');
 require('../__chunks/H7R5D2FR.cjs');
 require('../__chunks/NHZBX2RS.cjs');
-require('../__chunks/BFLDQF3L.cjs');
+require('../__chunks/GQAB4M3B.cjs');
 require('../__chunks/LHHW5ZQP.cjs');
 require('../__chunks/Z5PUIG6A.cjs');
-require('../__chunks/I63PYP2U.cjs');
+require('../__chunks/UHRHLHM2.cjs');
 require('../__chunks/5WLTMVVQ.cjs');
 require('../__chunks/7WUTS26Y.cjs');
 require('../__chunks/72I2GWXF.cjs');
 
 
 
-exports.Radio = _ZJ4ICN62cjs.Radio; exports.useRadio = _ZJ4ICN62cjs.useRadio;
+exports.Radio = _L4TB7MRWcjs.Radio; exports.useRadio = _L4TB7MRWcjs.useRadio;

package/cjs/radio/radio.d.ts

@@ -32,8 +32,12 @@ export declare const useRadio: import("../utils/types.js").Hook<RadioOptions<"in
 export declare const Radio: import("../utils/types.js").Component<RadioOptions<"input">>;
 export interface RadioOptions<T extends As = "input"> extends CompositeItemOptions<T> {
     /**
-     * Object returned by the `useRadioStore` hook. If not provided, the parent
-     * `RadioGroup` component's context will be used.
+     * Object returned by the
+     * [`useRadioStore`](https://ariakit.org/reference/use-radio-store) hook. If
+     * not provided, the closest
+     * [`RadioGroup`](https://ariakit.org/reference/radio-group) or
+     * [`RadioProvider`](https://ariakit.org/reference/radio-provider) components'
+     * context will be used.
      */
     store?: RadioStore;
     /**

package/cjs/select/select-arrow.d.ts

@@ -21,26 +21,31 @@ import type { SelectStore } from "./select-store.js";
 export declare const useSelectArrow: import("../utils/types.js").Hook<SelectArrowOptions<"span">>;
 /**
  * Renders an arrow pointing to the select popover position. It's usually
- * rendered inside the `Select` component.
+ * rendered inside the [`Select`](https://ariakit.org/reference/select)
+ * component.
  * @see https://ariakit.org/components/select
  * @example
  * ```jsx
- * const select = useSelectStore();
- * <Select store={select}>
- *   {select.value}
- *   <SelectArrow />
- * </Select>
- * <SelectPopover store={select}>
- *   <SelectItem value="Apple" />
- *   <SelectItem value="Orange" />
- * </SelectPopover>
+ * <SelectProvider>
+ *   <Select>
+ *     {select.value}
+ *     <SelectArrow />
+ *   </Select>
+ *   <SelectPopover>
+ *     <SelectItem value="Apple" />
+ *     <SelectItem value="Orange" />
+ *   </SelectPopover>
+ * </SelectProvider>
  * ```
  */
 export declare const SelectArrow: import("../utils/types.js").Component<SelectArrowOptions<"span">>;
 export interface SelectArrowOptions<T extends As = "span"> extends PopoverDisclosureArrowOptions<T> {
     /**
-     * Object returned by the `useSelectStore` hook. If not provided, the parent
-     * `Select` component's context will be used.
+     * Object returned by the
+     * [`useSelectStore`](https://ariakit.org/reference/use-select-store) hook. If
+     * not provided, the closest [`Select`](https://ariakit.org/reference/select)
+     * or [`SelectProvider`](https://ariakit.org/reference/select-provider)
+     * components' context will be used.
      */
     store?: SelectStore;
 }

package/cjs/select/select-group-label.d.ts

@@ -21,27 +21,32 @@ export declare const useSelectGroupLabel: import("../utils/types.js").Hook<Selec
  * @see https://ariakit.org/components/select
  * @example
  * ```jsx
- * const select = useSelectStore();
- * <Select store={select} />
- * <SelectPopover store={select}>
- *   <SelectGroup>
- *     <SelectGroupLabel>Fruits</SelectGroupLabel>
- *     <SelectItem value="Apple" />
- *     <SelectItem value="Orange" />
- *   </SelectGroup>
- *   <SelectGroup>
- *     <SelectGroupLabel>Meat</SelectGroupLabel>
- *     <SelectItem value="Beef" />
- *     <SelectItem value="Chicken" />
- *   </SelectGroup>
- * </SelectPopover>
+ * <SelectProvider>
+ *   <Select />
+ *   <SelectPopover>
+ *     <SelectGroup>
+ *       <SelectGroupLabel>Fruits</SelectGroupLabel>
+ *       <SelectItem value="Apple" />
+ *       <SelectItem value="Orange" />
+ *     </SelectGroup>
+ *     <SelectGroup>
+ *       <SelectGroupLabel>Meat</SelectGroupLabel>
+ *       <SelectItem value="Beef" />
+ *       <SelectItem value="Chicken" />
+ *     </SelectGroup>
+ *   </SelectPopover>
+ * </SelectProvider>
  * ```
  */
 export declare const SelectGroupLabel: import("../utils/types.js").Component<SelectGroupLabelOptions<"div">>;
 export interface SelectGroupLabelOptions<T extends As = "div"> extends CompositeGroupLabelOptions<T> {
     /**
-     * Object returned by the `useSelectStore` hook. If not provided, the parent
-     * `SelectList` or `SelectPopover` components' context will be used.
+     * Object returned by the
+     * [`useSelectStore`](https://ariakit.org/reference/use-select-store) hook. If
+     * not provided, the parent
+     * [`SelectList`](https://ariakit.org/reference/select-list) or
+     * [`SelectPopover`](https://ariakit.org/reference/select-popover) components'
+     * context will be used.
      */
     store?: SelectStore;
 }

package/cjs/select/select-group.d.ts

@@ -24,22 +24,27 @@ export declare const useSelectGroup: import("../utils/types.js").Hook<SelectGrou
  * @see https://ariakit.org/components/select
  * @example
  * ```jsx
- * const select = useSelectStore();
- * <Select store={select} />
- * <SelectPopover store={select}>
- *   <SelectGroup>
- *     <SelectGroupLabel>Fruits</SelectGroupLabel>
- *     <SelectItem value="Apple" />
- *     <SelectItem value="Orange" />
- *   </SelectGroup>
- * </SelectPopover>
+ * <SelectProvider>
+ *   <Select />
+ *   <SelectPopover>
+ *     <SelectGroup>
+ *       <SelectGroupLabel>Fruits</SelectGroupLabel>
+ *       <SelectItem value="Apple" />
+ *       <SelectItem value="Orange" />
+ *     </SelectGroup>
+ *   </SelectPopover>
+ * </SelectProvider>
  * ```
  */
 export declare const SelectGroup: import("../utils/types.js").Component<SelectGroupOptions<"div">>;
 export interface SelectGroupOptions<T extends As = "div"> extends CompositeGroupOptions<T> {
     /**
-     * Object returned by the `useSelectStore` hook. If not provided, the parent
-     * `SelectList` or `SelectPopover` components' context will be used.
+     * Object returned by the
+     * [`useSelectStore`](https://ariakit.org/reference/use-select-store) hook. If
+     * not provided, the parent
+     * [`SelectList`](https://ariakit.org/reference/select-list) or
+     * [`SelectPopover`](https://ariakit.org/reference/select-popover) components'
+     * context will be used.
      */
     store?: SelectStore;
 }

package/cjs/select/select-item-check.d.ts

@@ -20,31 +20,37 @@ export declare const useSelectItemCheck: import("../utils/types.js").Hook<Select
  * @see https://ariakit.org/components/select
  * @example
  * ```jsx
- * const select = useSelectStore();
- * <Select store={select} />
- * <SelectPopover store={select}>
- *   <SelectItem value="Apple">
- *     <SelectItemCheck />
- *     Apple
- *   </SelectItem>
- *   <SelectItem value="Orange">
- *     <SelectItemCheck />
- *     Orange
- *   </SelectItem>
- * </SelectPopover>
+ * <SelectProvider>
+ *   <Select />
+ *   <SelectPopover>
+ *     <SelectItem value="Apple">
+ *       <SelectItemCheck />
+ *       Apple
+ *     </SelectItem>
+ *     <SelectItem value="Orange">
+ *       <SelectItemCheck />
+ *       Orange
+ *     </SelectItem>
+ *   </SelectPopover>
+ * </SelectProvider>
  * ```
  */
 export declare const SelectItemCheck: import("../utils/types.js").Component<SelectItemCheckOptions<"span">>;
 export interface SelectItemCheckOptions<T extends As = "span"> extends CheckboxCheckOptions<T> {
     /**
-     * Object returned by the `useSelectStore` hook. If not provided, the parent
-     * `SelectList` or `SelectPopover` components' context will be used.
+     * Object returned by the
+     * [`useSelectStore`](https://ariakit.org/reference/use-select-store) hook. If
+     * not provided, the parent
+     * [`SelectList`](https://ariakit.org/reference/select-list) or
+     * [`SelectPopover`](https://ariakit.org/reference/select-popover) components'
+     * context will be used.
      */
     store?: SelectStore;
     /**
      * Whether the check mark should be shown. This value is automatically
-     * inferred from the parent `SelectItem` component. Manually setting this prop
-     * will override the inferred value.
+     * inferred from the parent
+     * [`SelectItem`](https://ariakit.org/reference/select-item) component.
+     * Manually setting this prop will override the inferred value.
      */
     checked?: boolean;
 }

package/cjs/select/select-item.cjs

@@ -7,8 +7,8 @@ var _LPFT4ZFHcjs = require('../__chunks/LPFT4ZFH.cjs');
 var _I2EPCLS6cjs = require('../__chunks/I2EPCLS6.cjs');
 
 
-var _G33PRHOGcjs = require('../__chunks/G33PRHOG.cjs');
-require('../__chunks/NPDPNCSD.cjs');
+var _D3SPQ2OYcjs = require('../__chunks/D3SPQ2OY.cjs');
+require('../__chunks/FXRXBA2Y.cjs');
 require('../__chunks/FMI5QF7N.cjs');
 require('../__chunks/KLZID3QO.cjs');
 require('../__chunks/H7R5D2FR.cjs');
@@ -16,14 +16,14 @@ require('../__chunks/NHZBX2RS.cjs');
 require('../__chunks/AKOG5S2T.cjs');
 require('../__chunks/W6ZRSMO5.cjs');
 require('../__chunks/A2NMYLCG.cjs');
-require('../__chunks/BFLDQF3L.cjs');
+require('../__chunks/GQAB4M3B.cjs');
 require('../__chunks/LHHW5ZQP.cjs');
 
 
 
 
 var _Z5PUIG6Acjs = require('../__chunks/Z5PUIG6A.cjs');
-require('../__chunks/I63PYP2U.cjs');
+require('../__chunks/UHRHLHM2.cjs');
 
 
 
@@ -151,7 +151,7 @@ var useSelectItem = _Z5PUIG6Acjs.createHook.call(void 0,
       autoFocus: (_a2 = props.autoFocus) != null ? _a2 : autoFocus,
       onClick
     });
-    props = _G33PRHOGcjs.useCompositeItem.call(void 0, _72I2GWXFcjs.__spreadValues.call(void 0, {
+    props = _D3SPQ2OYcjs.useCompositeItem.call(void 0, _72I2GWXFcjs.__spreadValues.call(void 0, {
       store,
       getItem,
       preventScrollOnKeyDown

package/cjs/select/select-item.d.ts

@@ -16,39 +16,64 @@ import type { SelectStore } from "./select-store.js";
  */
 export declare const useSelectItem: import("../utils/types.js").Hook<SelectItemOptions<"div">>;
 /**
- * Renders a select item inside a select list or select popover. The `role` prop
- * will be automatically set based on the `SelectList` or `SelectPopover` own
- * `role` prop. For example, if the `SelectPopover` component's `role` prop is
- * set to `listbox` (default), the `SelectItem` `role` will be set to `option`.
- * By default, the `value` prop will be rendered as the children, but this can
- * be overriden.
+ * Renders a select item inside a
+ * [`SelectList`](https://ariakit.org/reference/select-list) or
+ * [`SelectPopover`](https://ariakit.org/reference/select-popover).
+ *
+ * The `role` attribute will be automatically set on the item based on the
+ * list's own `role` attribute. For example, if the
+ * [`SelectPopover`](https://ariakit.org/reference/select-popover) component's
+ * `role` attribute is set to `listbox` (which is the default), the item `role`
+ * will be set to `option`.
+ *
+ * By default, the [`value`](https://ariakit.org/reference/select-item#value)
+ * prop will be rendered as the children, but this can be overriden if a custom
+ * children is provided.
  * @see https://ariakit.org/components/select
  * @example
- * ```jsx
- * const select = useSelectStore();
- * <Select store={select} />
- * <SelectPopover store={select}>
- *   <SelectItem value="Apple" />
- *   <SelectItem value="Orange" />
- * </SelectPopover>
+ * ```jsx {4-5}
+ * <SelectProvider>
+ *   <Select />
+ *   <SelectPopover>
+ *     <SelectItem value="Apple" />
+ *     <SelectItem value="Orange" />
+ *   </SelectPopover>
+ * </SelectProvider>
  * ```
  */
 export declare const SelectItem: import("../utils/types.js").Component<SelectItemOptions<"div">>;
 export interface SelectItemOptions<T extends As = "div"> extends CompositeItemOptions<T>, CompositeHoverOptions<T> {
     /**
-     * Object returned by the `useSelectStore` hook. If not provided, the parent
-     * `SelectList` or `SelectPopover` components' context will be used.
+     * Object returned by the
+     * [`useSelectStore`](https://ariakit.org/reference/use-select-store) hook. If
+     * not provided, the parent
+     * [`SelectList`](https://ariakit.org/reference/select-list) or
+     * [`SelectPopover`](https://ariakit.org/reference/select-popover) components'
+     * context will be used.
      */
     store?: SelectStore;
     /**
      * The value of the item. This will be rendered as the children by default.
-     *   - If `setValueOnClick` is set to `true` on this component, the
-     *     `select.value` state will be set to this value when the user clicks on
-     *     it.
-     *   - If `select.setValueOnMove` is set to `true` on the select store, the
-     *     `select.value` state will be set to this value when the user moves to
-     *     it (which is usually the case when moving through the items using the
-     *     keyboard).
+     * - If
+     *   [`setValueOnClick`](https://ariakit.org/reference/select-item#setvalueonclick)
+     *   is set to `true`, the
+     *   [`value`](https://ariakit.org/reference/select-provider#value) state will
+     *   be set to this value when the user clicks on it.
+     * - If
+     *   [`setValueOnMove`](https://ariakit.org/reference/select-provider#setvalueonmove)
+     *   is set to `true`, the
+     *   [`value`](https://ariakit.org/reference/select-provider#value) state will
+     *   be set to this value when the user moves to it (which is usually the case
+     *   when moving through the items using the keyboard).
+     *
+     * Live examples:
+     * - [Form with Select](https://ariakit.org/examples/form-select)
+     * - [Animated Select](https://ariakit.org/examples/select-animated)
+     * - [Select with Combobox](https://ariakit.org/examples/select-combobox)
+     * - [Select grid](https://ariakit.org/examples/select-grid)
+     * - [SelectGroup](https://ariakit.org/examples/select-group)
+     * - [Select with custom
+     *   item](https://ariakit.org/examples/select-item-custom)
      * @example
      * ```jsx
      * <SelectItem value="Apple" />
@@ -57,12 +82,14 @@ export interface SelectItemOptions<T extends As = "div"> extends CompositeItemOp
     value?: string;
     /**
      * Whether to hide the select when this item is clicked. By default, it's
-     * `true` when the `value` prop is also provided.
+     * `true` when the [`value`](https://ariakit.org/reference/select-item#value)
+     * prop is also provided.
      */
     hideOnClick?: BooleanOrCallback<MouseEvent<HTMLElement>>;
     /**
      * Whether to set the select value with this item's value, if any, when this
-     * item is clicked. By default, it's `true` when the `value` prop is also
+     * item is clicked. By default, it's `true` when the
+     * [`value`](https://ariakit.org/reference/select-item#value) prop is also
      * provided.
      */
     setValueOnClick?: BooleanOrCallback<MouseEvent<HTMLElement>>;