PnP React Hooks

PnP React Hooks is a wrapper library for PnPjs, provides configurable React hooks for SharePoint API to speed up development for simple SPFx webparts and components.

Example usage:

import * as React from "react";
import { useListItems, useCurrentUser } from "pnp-react-hooks";

export const ExampleComponent = () => {
	const currentUser = useCurrentUser();

	const items = useListItems("My List", {
		query: {
			select: ["Title", "Id", "Author/Title"],
			expand: ["Author"],
			filter: `Author eq ${currentUser?.Id}`
		},
		disabled: !currentUser
	});

	return (<ul>
		{items?.map(item => (<li key={item.Id}>{item.Title}</li>))}
	</ul>);
};

Installation

npm install pnp-react-hooks @pnp/sp react

@pnp/sp and react packages are peer dependencies.

Peer dependency	Supported versions
`@pnp/sp`	4.1.0 or later
`react`	16.9.* to 18..

Features

Build simple web parts quickly with less code.
TypeScript support.
Automatically tracks parameter changes and refreshes data as needed.
Easy to tree-shake unused code with modern JS bundlers.
Can be configured for multiple sites with an option provider.
Supports PnPjs behaviors.

Questions and Suggestions

If you find any issue or have a suggestion on how project can be improved feel free to create an issue on Github.

Getting Started

SPFx

Install pnp-react-hooks and @pnp/sp packages to your SPFx webpart project.

npm install pnp-react-hooks @pnp/sp

Update module imports, onInit() and render() functions on <YourWebpartName>.tsx file.

PnpReactHookExamplesWebPart.ts

// <Other Webpart imports>
// Import pnp-react-hooks helper function and option type
import { PnpHookGlobalOptions, createProviderElement } from 'pnp-react-hooks';
// import PnPjs
import { spfi, SPFx} from '@pnp/sp';

export default class PnpReactHookExamplesWebPart extends BaseClientSideWebPart<IPnpReactHookExamplesWebPartProps>
{
  private _isDarkTheme: boolean = false;
  private _environmentMessage: string = '';
  private _theme: IReadonlyTheme;
  private _hookOptions: PnpHookGlobalOptions;

  // Create onInit function to initialize options.
  protected onInit(): Promise<void>
  {
    return this._getEnvironmentMessage().then(message =>
    {
      this._environmentMessage = message;
      // Initialize PnPjs sp context.
      const sp = spfi().using(SPFx(this.context));

      // Setup your default PnP React hooks options.
      this._hookOptions = {
        sp: sp,
        disabled: "auto"
      };
    });
  }

  public render(): void
  {
    const element: React.ReactElement<IPnpReactHookExamplesProps> = React.createElement(
      PnpReactHookExamples,
      {
        description: this.properties.description,
      }
    );

    // Use helper function to create React elements.
    const rootElement = createProviderElement(this._hookOptions, element);

    // Render root element.
    ReactDom.render(rootElement, this.domElement);
  }

}

Start using hooks in your webpart components.

PnpReactHookExamples.tsx

import * as React from 'react';
import { IPnpReactHookExamplesProps } from './IPnpReactHookExamplesProps';
import { useCurrentUser } from "pnp-react-hooks";

const PnpReactHookExamples = (props: IPnpReactHookExamplesProps) => {
  const me = useCurrentUser({
    query: {
    select: ["Title"]
  }
});

return (<div>{me?.Title}</div>);
};

export default PnpReactHookExamples;

Common Hook Options

All hook options have the following common properties:

disabled: Disables hook execution if supplied value or predicate function result is true. It also supports "auto" which handles the common cases like null list name, undefined user name etc.

query: OData query parameters supported by resource type. Automatically tracked for changes with deep comparison.

For example, the following query1 and query2 are considered as equal and they won't cause any re-render.

const query1 = {
    select: ["Title", "Id", "Lookup/Id"],
    expand: ["Lookup"]
}

const query2 = {
    expand: ["Lookup"]
    select: ["Id", "Lookup/Id", "Title"],
}

keepPreviousState: When enabled, hook does not reset it's current state to undefined before sending a new request.

sp: Overrides PnpJs SPFI instance. Default uses context-provided instance.

behaviors: Sets PnpJs pipeline behaviors to each request.

error: Error handling mode or custom error callback. Use ErrorMode.Default (0) for throwing error, ErrorMode.Suppress (1) for ignoring the errors.

type PnpHookOptions = {
    disabled?: "auto" | boolean | (...args[]) => boolean;
    query?: {
        expand?: string[];
        select?: string[];
        // Extra properties are available for collection types.
        top?: number;
        orderBy?: string;
        orderyByAscending?: boolean;
        skip?: number;
        filter?: string;
    },
    keepPreviousState?: boolean;
    sp?: SPFI;
    behaviors?: TimelinePipe<any>[];
    error?: 0 | 1 | (err:Error) => void;
}

Option Provider

All hooks can be configured with PnpHookOptionProvider component. SP Hooks use options from the nearest parent provider similar to how React contexts works.

import * as React from "react";
import { useWebInfo, PnpHookOptionProvider, PnpHookGlobalOptions } from "pnp-react-hooks";
import { Caching } from "@pnp/queryable";
import { spfi, SPBrowser } from "@pnp/sp";

/** @type{PnpHookGlobalOptions} **/
const options = {
    disabled: "auto",
    keepPreviousState: true,
    error: console.debug,
    sp: spfi().using(SPBrowser())
};

/** @type{PnpHookGlobalOptions} **/
const cachedOptions = {
    disabled: "auto",
    keepPreviousState: true,
    error: console.debug,
    sp: spfi().using(SPBrowser(), Caching())
};

export function Main() {
    return(
        <>
            <PnpHookOptionProvider value={options}>
                <CurrentWebInfo />
                <UserInfo />
            </PnpHookOptionProvider>
            <PnpHookOptionProvider value={cachedOptions}>
                <CurrentWebInfo />
                <UserInfo />
            </PnpHookOptionProvider>
        </>
    );
}

export function CurrentWebInfo() {
    const web = useWebInfo();
    return <h1>{web?.Title}</h1>;
}

export function UserInfo() {
    const user = useCurrentUser();
    return <h2>{user?.Title}</h2>;
}

For non-Jsx initializers, PnpHookOptionProvider can be created with createProviderElement function.

createProviderElement(options: PnpHOokGlobalOptions, ...children: any[]);

import * as React from "react";
import * as ReactDom from "react-dom";
import { spfi, SPBrowser } from "@pnp/sp";
import { createProviderElement, PnpHookGlobalOptions } from 'pnp-react-hooks';

// create options
const options: PnpHookGlobalOptions = {
    sp: spfi("<sharepoint-site-url>").using(SPBrowser()),
    disabled: "auto",
    error: (err) => console.debug(err)
};

// Create your child elements
const childElement0 = React.createElement(PnpReactHookExamples, { description: "Child 0" });
const childElement1 = React.createElement(PnpReactHookExamples, { description: "Child 1" });

// Create root element with provider
const rootElement = createProviderElement(options, childElement0, childElement1);

ReactDom.render(rootElement, this.domElement);

Created React DOM tree is:

<PnpHookOptionProvider value={options}>
    <PnpReactHookExamples description="Child 0" />
    <PnpReactHookExamples description="Child 1" />
</PnpHookOptionProvider>

Accessing Options

usePnpHookOptions(): PnpHookGlobalOptions;

Returns options from the nearest PnpHookOptionProvider.

Example

import { usePnpHookOptions } from "pnp-react-hooks";

function ExampleComponent() {
    const options = usePnpHookOptions();

    .....
    .....
    .....
    .....
}

Sp Hooks

useApp

useApp<T>(appId: string, options?:WebAppOptions, deps?: any[]) : T | null | undefined;

Returns an app details for the given Id.

Name	Type	Description	Tracked for changes
`appId`	`string`	App UUID string.	Yes
`options?`	`WebAppOptions`	useApp hook options	Partially
`deps?`	`DependencyList`	Hook dependency list.	Yes

Name	Type	Description	Tracked for changes
`options?`	`WebAppsOptions`	useApps hook options	Partially
`deps?`	`DependencyList`	Hook dependency list.	Yes

Name	Type	Description	Tracked for changes
`attachmentName`	`string`	Attachment name	Yes
`itemId`	`number`	List item ID	Yes
`list`	`string`	Target list UUID or title	Yes
`options?`	`AttachmentInfoOptions` \| `AttachmentBlobOptions` \| `AttachmentTextOptions` \| `AttachmentBufferOptions`	useAttachment hook options	Partially
`deps?`	`DependencyList`	Hook dependency list.	Yes

Name	Type	Description	Tracked for changes
`itemId`	`number`	List item ID	Yes
`list`	`string`	Target list UUID or title	Yes
`options?`	`ItemAttachmentsOptions`	useAttachments hook options	Partially
`deps?`	`DependencyList`	Hook dependency list.	Yes