@fluentui/react-hooks package

Interfaces

IUseBooleanCallbacks

Updater callbacks returned by useBoolean.

IWarningOptions

Functions

useAsync()

Hook to provide an Async instance that is automatically cleaned up on dismount.

useBoolean(initialState)

Hook to store a value and generate callbacks for setting the value to true or false. The identity of the callbacks will always stay the same.

useConst(initialValue)

Hook to initialize and return a constant value. Unlike React.useMemo, this is guaranteed to always return the same value (and if the initializer is a function, only call it once). This is similar to setting a private member in a class constructor.

If the value should ever change based on dependencies, use React.useMemo instead.

useConstCallback(callback)
useControllableValue(controlledValue, defaultUncontrolledValue)

Hook to manage a value that could be either controlled or uncontrolled, such as a checked state or text box string.

useControllableValue(controlledValue, defaultUncontrolledValue, onChange)
useForceUpdate()

Hook to force update a function component by updating a dummy state.

useId(prefix, providedId)

Hook to generate a unique ID in the global scope (spanning across duplicate copies of the same library).

useMergedRefs(refs)

React hook to merge multiple React refs (either MutableRefObjects or ref callbacks) into a single ref callback that updates all provided refs

useOnEvent(element, eventName, callback, useCapture)

Hook to attach an event handler on mount and handle cleanup.

usePrevious(value)

Hook keeping track of a given value from a previous execution of the component the Hook is used in.

See [React Hooks FAQ](https://reactjs.org/docs/hooks-faq.html\#how-to-get-the-previous-props-or-state)

useRefEffect(callback, initial)

Creates a ref, and calls a callback whenever the ref changes to a non-null value. The callback can optionally return a cleanup function that'll be called before the value changes, and when the ref is unmounted.

This can be used to work around a limitation that useEffect cannot depend on ref.current (see https://github.com/facebook/react/issues/14387\#issuecomment-503616820).

Usage example:

const myRef = useRefEffect<HTMLElement>(element => {
 ...
 return () => { ... cleanup ... };
});

<div ref={myRef} />

useTarget(target, hostElement)

Hook to calculate and cache the target element specified by the given target attribute, as well as the target element's (or host element's) parent window

useWarnings(options)

Only in development mode, display console warnings when certain conditions are met. Note that all warnings except controlledUsage will only be shown on first render (new controlledUsage warnings may be shown later due to prop changes).

Function Details

useAsync()

Hook to provide an Async instance that is automatically cleaned up on dismount.

export declare function useAsync(): Async;

Returns

useBoolean(initialState)

Hook to store a value and generate callbacks for setting the value to true or false. The identity of the callbacks will always stay the same.

export declare function useBoolean(initialState: boolean): [boolean, IUseBooleanCallbacks];

Parameters

initialState

boolean

Initial value

Returns

[boolean, IUseBooleanCallbacks]

Array with the current value and an object containing the updater callbacks.

useConst(initialValue)

Hook to initialize and return a constant value. Unlike React.useMemo, this is guaranteed to always return the same value (and if the initializer is a function, only call it once). This is similar to setting a private member in a class constructor.

If the value should ever change based on dependencies, use React.useMemo instead.

export declare function useConst<T>(initialValue: T | (() => T)): T;

Parameters

initialValue

T | (() => T)

Initial value, or function to get the initial value. Similar to useState, only the value/function passed in the first time this is called is respected.

Returns

T

The value. The identity of this value will always be the same.

useConstCallback(callback)

Warning

This API is now deprecated.

Deprecated due to potential for misuse (see package readme). Use React.useCallback instead.

export declare function useConstCallback<T extends (...args: any[]) => any>(callback: T): T;

Parameters

callback

T

Returns

T

useControllableValue(controlledValue, defaultUncontrolledValue)

Hook to manage a value that could be either controlled or uncontrolled, such as a checked state or text box string.

export declare function useControllableValue<TValue, TElement extends HTMLElement>(controlledValue: TValue | undefined, defaultUncontrolledValue: TValue | undefined): Readonly<[TValue | undefined, (update: React.SetStateAction<TValue | undefined>) => void]>;

Parameters

controlledValue

TValue | undefined

The controlled value passed in the props. This value will always be used if provided, and the internal state will be updated to reflect it.

defaultUncontrolledValue

TValue | undefined

Initial value for the internal state in the uncontrolled case.

Returns

Readonly<[TValue | undefined, (update: React.SetStateAction<TValue | undefined>) => void]>

An array of the current value and an updater callback. Like React.useState, the updater callback always has the same identity, and it can take either a new value, or a function which is passed the previous value and returns the new value. https://reactjs.org/docs/uncontrolled-components.html

useControllableValue(controlledValue, defaultUncontrolledValue, onChange)

export declare function useControllableValue<TValue, TElement extends HTMLElement, TEvent extends React.SyntheticEvent<TElement> | undefined>(controlledValue: TValue | undefined, defaultUncontrolledValue: TValue | undefined, onChange: ChangeCallback<TElement, TValue, TEvent> | undefined): Readonly<[TValue | undefined, (update: React.SetStateAction<TValue | undefined>, ev?: React.FormEvent<TElement>) => void]>;

Parameters

controlledValue

TValue | undefined

defaultUncontrolledValue

TValue | undefined

onChange

ChangeCallback<TElement, TValue, TEvent> | undefined

Returns

Readonly<[TValue | undefined, (update: React.SetStateAction<TValue | undefined>, ev?: React.FormEvent<TElement>) => void]>

useForceUpdate()

Hook to force update a function component by updating a dummy state.

export declare function useForceUpdate(): () => void;

Returns

() => void

useId(prefix, providedId)

Hook to generate a unique ID in the global scope (spanning across duplicate copies of the same library).

export declare function useId(prefix?: string, providedId?: string): string;

Parameters

prefix

string

Optional prefix for the ID

providedId

string

Optional id provided by a parent component. Defaults to the provided value if present, without conditioning the hook call

Returns

string

The ID

useMergedRefs(refs)

React hook to merge multiple React refs (either MutableRefObjects or ref callbacks) into a single ref callback that updates all provided refs

export declare function useMergedRefs<T>(...refs: (React.Ref<T> | undefined)[]): RefObjectFunction<T>;

Parameters

refs

(React.Ref<T> | undefined)[]

Refs to collectively update with one ref value.

Returns

RefObjectFunction<T>

A function with an attached "current" prop, so that it can be treated like a RefObject.

useOnEvent(element, eventName, callback, useCapture)

Hook to attach an event handler on mount and handle cleanup.

export declare function useOnEvent<TElement extends Element, TEvent extends Event>(element: React.RefObject<TElement | undefined | null> | TElement | Window | Document | undefined | null, eventName: string, callback: (ev: TEvent) => void, useCapture?: boolean): void;

Parameters

element

React.RefObject<TElement | undefined | null> | TElement | Window | Document | undefined | null

Element (or ref to an element) to attach the event handler to

eventName

string

The event to attach a handler for

callback

(ev: TEvent) => void

The handler for the event

useCapture

boolean

Whether or not to attach the handler for the capture phase

Returns

void

usePrevious(value)

Hook keeping track of a given value from a previous execution of the component the Hook is used in.

See [React Hooks FAQ](https://reactjs.org/docs/hooks-faq.html\#how-to-get-the-previous-props-or-state)

export declare function usePrevious<T>(value: T): T | undefined;

Parameters

value

T

Returns

T | undefined

useRefEffect(callback, initial)

Creates a ref, and calls a callback whenever the ref changes to a non-null value. The callback can optionally return a cleanup function that'll be called before the value changes, and when the ref is unmounted.

This can be used to work around a limitation that useEffect cannot depend on ref.current (see https://github.com/facebook/react/issues/14387\#issuecomment-503616820).

Usage example:

const myRef = useRefEffect<HTMLElement>(element => {
 ...
 return () => { ... cleanup ... };
});

<div ref={myRef} />

export declare function useRefEffect<T>(callback: (value: T) => (() => void) | void, initial?: T | null): RefCallback<T>;

Parameters

callback

(value: T) => (() => void) | void

Called whenever the ref's value changes to non-null. Can optionally return a cleanup function.

initial

T | null

(Optional) The initial value for the ref.

Returns

RefCallback<T>

A function that should be called to set the ref's value. The object also has a .current member that can be used to access the ref's value (like a normal RefObject). It can be hooked up to an element's ref property.

useTarget(target, hostElement)

Hook to calculate and cache the target element specified by the given target attribute, as well as the target element's (or host element's) parent window

export declare function useTarget<TElement extends HTMLElement = HTMLElement>(target: Target | undefined, hostElement?: React.RefObject<TElement | null>): Readonly<[React.RefObject<Element | MouseEvent | Point | null>, Window | undefined]>;

Parameters

target

Target | undefined

Target selector passed to the component as a property, describing the element that the callout should target

hostElement

React.RefObject<TElement | null>

The callout's host element, used for determining the parent window.

Returns

Readonly<[React.RefObject<Element | MouseEvent | Point | null>, Window | undefined]>

useWarnings(options)

Only in development mode, display console warnings when certain conditions are met. Note that all warnings except controlledUsage will only be shown on first render (new controlledUsage warnings may be shown later due to prop changes).

export declare function useWarnings<P>(options: IWarningOptions<P>): void;

Parameters

options

IWarningOptions<P>

Returns

void