Types Primitives
A collection of hooks for core primitives.
Hooks
useAugmentedRef Allows using a forwarded ref as a value of useRef and allows adding properties to the ref.useControllableState Allows defaulting to an uncontrolled state and allows controlling the state from the parent.useRelativePosition Returns a style for an element relative to another element.Install the component via your command line.
npx expo install @rn-primitives/hooksCopy/paste the following code to ~/components/primitives/hooks/useAugmentedRef.tsx
import * as React from 'react';
interface AugmentRefProps<T> { ref: React.Ref<T>; methods?: Record<string, (...args: any[]) => any>; deps?: any[];}
export function useAugmentedRef<T>({ ref, methods, deps = [],}: AugmentRefProps<T>) { const augmentedRef = React.useRef<T>(null); React.useImperativeHandle( ref, () => { if (typeof augmentedRef === 'function' || !augmentedRef?.current) { return {} as T; } return { ...augmentedRef.current, ...methods, }; }, deps ); return augmentedRef;}Copy/paste the following code to ~/components/primitives/hooks/useControllableState.tsx
// This project uses code from WorkOS/Radix Primitives.// The code is licensed under the MIT License.// https://github.com/radix-ui/primitives/tree/main
import * as React from 'react';
type UseControllableStateParams<T> = { prop?: T | undefined; defaultProp?: T | undefined; onChange?: (state: T) => void;};
type SetStateFn<T> = (prevState?: T) => T;
function useControllableState<T>({ prop, defaultProp, onChange = () => {},}: UseControllableStateParams<T>) { const [uncontrolledProp, setUncontrolledProp] = useUncontrolledState({ defaultProp, onChange }); const isControlled = prop !== undefined; const value = isControlled ? prop : uncontrolledProp; const handleChange = useCallbackRef(onChange);
const setValue: React.Dispatch<React.SetStateAction<T | undefined>> = React.useCallback( (nextValue) => { if (isControlled) { const setter = nextValue as SetStateFn<T>; const value = typeof nextValue === 'function' ? setter(prop) : nextValue; if (value !== prop) handleChange(value as T); } else { setUncontrolledProp(nextValue); } }, [isControlled, prop, setUncontrolledProp, handleChange] );
return [value, setValue] as const;}
function useUncontrolledState<T>({ defaultProp, onChange,}: Omit<UseControllableStateParams<T>, 'prop'>) { const uncontrolledState = React.useState<T | undefined>(defaultProp); const [value] = uncontrolledState; const prevValueRef = React.useRef(value); const handleChange = useCallbackRef(onChange);
React.useEffect(() => { if (prevValueRef.current !== value) { handleChange(value as T); prevValueRef.current = value; } }, [value, prevValueRef, handleChange]);
return uncontrolledState;}
/** * A custom hook that converts a callback to a ref to avoid triggering re-renders when passed as a * prop or avoid re-executing effects when passed as a dependency */function useCallbackRef<T extends (...args: any[]) => any>(callback: T | undefined): T { const callbackRef = React.useRef(callback);
React.useEffect(() => { callbackRef.current = callback; });
// https://github.com/facebook/react/issues/19240 return React.useMemo(() => ((...args) => callbackRef.current?.(...args)) as T, []);}
export { useControllableState };Copy/paste the following code to ~/components/primitives/hooks/useRelativePosition.tsx
import type { Insets } from '~/components/primitives/types';import * as React from 'react';import { Dimensions, type LayoutRectangle, type ScaledSize, type ViewStyle } from 'react-native';
const POSITION_ABSOLUTE: ViewStyle = { position: 'absolute',};
const HIDDEN_CONTENT: ViewStyle = { position: 'absolute', opacity: 0, zIndex: -9999999,};
type UseRelativePositionArgs = Omit< GetContentStyleArgs, 'triggerPosition' | 'contentLayout' | 'dimensions'> & { triggerPosition: LayoutPosition | null; contentLayout: LayoutRectangle | null; disablePositioningStyle?: boolean;};
export function useRelativePosition({ align, avoidCollisions, triggerPosition, contentLayout, alignOffset, insets, sideOffset, side, disablePositioningStyle,}: UseRelativePositionArgs) { const dimensions = Dimensions.get('screen');
return React.useMemo(() => { if (disablePositioningStyle) { return {}; } if (!triggerPosition || !contentLayout) { return HIDDEN_CONTENT; } return getContentStyle({ align, avoidCollisions, contentLayout, side, triggerPosition, alignOffset, insets, sideOffset, dimensions, }); }, [ align, avoidCollisions, side, alignOffset, insets, triggerPosition, contentLayout, dimensions.width, dimensions.height, ]);}
export interface LayoutPosition { pageY: number; pageX: number; width: number; height: number;}
interface GetPositionArgs { dimensions: ScaledSize; avoidCollisions: boolean; triggerPosition: LayoutPosition; contentLayout: LayoutRectangle; insets?: Insets;}
interface GetSidePositionArgs extends GetPositionArgs { side: 'top' | 'bottom'; sideOffset: number;}
function getSidePosition({ side, triggerPosition, contentLayout, sideOffset, insets, avoidCollisions, dimensions,}: GetSidePositionArgs) { const insetTop = insets?.top ?? 0; const insetBottom = insets?.bottom ?? 0; const positionTop = triggerPosition?.pageY - sideOffset - contentLayout.height; const positionBottom = triggerPosition.pageY + triggerPosition.height + sideOffset;
if (!avoidCollisions) { return { top: side === 'top' ? positionTop : positionBottom, }; }
if (side === 'top') { return { top: Math.min( Math.max(insetTop, positionTop), dimensions.height - insetBottom - contentLayout.height ), }; }
return { top: Math.min(dimensions.height - insetBottom - contentLayout.height, positionBottom), };}
interface GetAlignPositionArgs extends GetPositionArgs { align: 'start' | 'center' | 'end'; alignOffset: number;}
function getAlignPosition({ align, avoidCollisions, contentLayout, triggerPosition, alignOffset, insets, dimensions,}: GetAlignPositionArgs) { const insetLeft = insets?.left ?? 0; const insetRight = insets?.right ?? 0; const maxContentWidth = dimensions.width - insetLeft - insetRight;
const contentWidth = Math.min(contentLayout.width, maxContentWidth);
let left = getLeftPosition( align, triggerPosition.pageX, triggerPosition.width, contentWidth, alignOffset, insetLeft, insetRight, dimensions );
if (avoidCollisions) { const doesCollide = left < insetLeft || left + contentWidth > dimensions.width - insetRight; if (doesCollide) { const spaceLeft = left - insetLeft; const spaceRight = dimensions.width - insetRight - (left + contentWidth);
if (spaceLeft > spaceRight && spaceLeft >= contentWidth) { left = insetLeft; } else if (spaceRight >= contentWidth) { left = dimensions.width - insetRight - contentWidth; } else { const centeredPosition = Math.max( insetLeft, (dimensions.width - contentWidth - insetRight) / 2 ); left = centeredPosition; } } }
return { left, maxWidth: maxContentWidth };}
function getLeftPosition( align: 'start' | 'center' | 'end', triggerPageX: number, triggerWidth: number, contentWidth: number, alignOffset: number, insetLeft: number, insetRight: number, dimensions: ScaledSize) { let left = 0; if (align === 'start') { left = triggerPageX; } if (align === 'center') { left = triggerPageX + triggerWidth / 2 - contentWidth / 2; } if (align === 'end') { left = triggerPageX + triggerWidth - contentWidth; } return Math.max( insetLeft, Math.min(left + alignOffset, dimensions.width - contentWidth - insetRight) );}
type GetContentStyleArgs = GetPositionArgs & GetSidePositionArgs & GetAlignPositionArgs;
function getContentStyle({ align, avoidCollisions, contentLayout, side, triggerPosition, alignOffset, insets, sideOffset, dimensions,}: GetContentStyleArgs) { return Object.assign( POSITION_ABSOLUTE, getSidePosition({ side, triggerPosition, contentLayout, sideOffset, insets, avoidCollisions, dimensions, }), getAlignPosition({ align, avoidCollisions, triggerPosition, contentLayout, alignOffset, insets, dimensions, }) );}Copy/paste the following code to ~/components/primitives/hooks/index.ts
export { useAugmentedRef } from './useAugmentedRef';export { useRelativePosition, type LayoutPosition } from './useRelativePosition';export { useControllableState } from './useControllableState';export { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';import { useAugmentedRef } from '@rn-primitives/hooks';import type { PressableRef, SlottablePressableProps } from '@rn-primitives/types';
const Thing = React.forwardRef<PressableRef, SlottablePressableProps>( (props, ref) => { const augmentedRef = useAugmentedRef({ ref });
React.useEffect(() => { if (augmentedRef.current) { // Do something with the augmented ref } }, []);
return ( <Pressable ref={augmentedRef} {...props} /> ); });import { useControllableState } from '@rn-primitives/hooks';import type { PressableRef, SlottablePressableProps } from '@rn-primitives/types';
const Thing = React.forwardRef<PressableRef, SlottablePressableProps & { defaultOpen?: boolean, open?: boolean, onOpenChange?: (open: boolean) => void }>( ({ defaultOpen, open: openProp, onOpenChange: onOpenChangeProp, onPress: onPressProp, ...props}, ref) => { const [open = false, onOpenChange] = useControllableState({ prop: openProp, defaultProp: defaultOpen, onChange: onOpenChangeProp, });
function onPress() { onOpenChange(!open); onPressProp?.(); }
return ( <Pressable ref={augmentedRef} onPress={onPress} {...props} /> ); });import { useRelativePosition } from '@rn-primitives/hooks';import type { PositionedContentProps, SlottablePressableProps, ViewRef } from '@rn-primitives/types';
const Content = React.forwardRef<ViewRef, SlottableViewProps & PositionedContentProps>( ( { align = 'center', side = 'top', sideOffset = 0, alignOffset = 0, avoidCollisions = true, onLayout: onLayoutProp, insets, style, disablePositioningStyle, ...props }, ref ) => { const { contentLayout, setContentLayout, triggerPosition, } = useRootContext();
const positionStyle = useRelativePosition({ align, avoidCollisions, triggerPosition, contentLayout, alignOffset, insets, sideOffset, side, disablePositioningStyle, });
function onLayout(event: LayoutChangeEvent) { setContentLayout(event.nativeEvent.layout); onLayoutProp?.(event); }
return ( <View ref={ref} style={[positionStyle, style]} onLayout={onLayout} {...props} /> ); });By default, children of all Portal components will be rendered as its own children.
| Prop | Type | Note |
|---|---|---|
| ref* | React.Ref<T> | |
| methods | Record<string, (…args: any[]) => any> | Added methods to the forwardRef. Allows the parent component that passes the ref to call the added methods (optional) |
| deps | Array<any> | Dependency array: a list of all reactive values referenced in the mothods (optional) |
| Prop | Type | Note |
|---|---|---|
| prop | T | undefined | (optional) |
| defaultProp | T | undefined | (optional) |
| onChange | (state: T | undefined) => void | (optional) |
| Prop | Type | Note |
|---|---|---|
| align* | ‘start’ | ‘center’ | ‘end’ | Horizontal alignment of content position relative to trigger |
| avoidCollisions* | boolean | Prevent content from going offscreen |
| triggerPosition* | LayoutPosition | null | Layout position of the trigger |
| contentLayout* | LayoutRectangle | null | Layout Size of the content |
| alignOffset* | number | Horizontal offset |
| insets* | LayoutRectangle | When avoidCollisions is true, it prevents content from going over insets |
| sideOffset* | number | Vertical offset |
| side* | ‘top’ | ‘bottom’; | Side alignment of content position relative to trigger |
| disablePositioningStyle* | boolean | Completely disables styling returned from hook |