SPFx FieldPicker Control — A Developer Configuration Tool for Dynamic SharePoint Solutions

When building solutions with SharePoint Framework (SPFx), one common challenge is avoiding hardcoded SharePoint field names.

Lists change.

Columns are renamed.

New metadata appears.

Internal names can be confusing.

That is where the FieldPicker control from PnP React Controls becomes valuable.

Official documentation:
PnP FieldPicker Documentation

But there is something important to understand:

FieldPicker is usually not an end-user control.

It is primarily a developer, administrator, or configuration tool.

That changes how we should think about it.

What is FieldPicker?

FieldPicker loads all available fields from a specific SharePoint list and allows selecting one or more of them.

Example:

<FieldPicker />

It retrieves metadata like:

• Display name
• Internal name
• Field type
• Hidden status
• Required status

This is useful because SharePoint often creates internal names differently from what users see.

Example:

As developers, we need the internal name.

Users do not.

Why is FieldPicker useful?

Imagine this code:

items.map(item => item.Status)

This works only if the column is literally named:

Status

But what if:

• the field changes
• the list is reused
• another site has different fields

Now the code breaks.

With FieldPicker:

items.map(item => item[selectedField.internalName])

Now the component becomes reusable.

This is one of the biggest advantages.

The most important concept

FieldPicker is often used during configuration time, not runtime.

That means:

Admin configures:

Use the "Status" field

The selection gets saved.

Then the web part uses it later.

End users never see FieldPicker.

Flow:

Developer/Admin → Select field → Save → Web part uses field dynamically

This is the correct mental model.

Your Example

Full component

import * as React from 'react';
import { FieldPicker } from "@pnp/spfx-controls-react/lib/FieldPicker";
interface IFieldPickerCtrProps {
    context: any;
}
const onFieldPickerChanged = (fields: any | any[]) => {
    console.log("Fields:", fields);
    console.log(JSON.stringify(fields, null, 2));
};
const FieldPickerCtr: React.FC<IFieldPickerCtrProps> = ({ context }) => {
    return (
        <FieldPicker
            context={context}
            includeHidden={false}
            includeReadOnly={false}
            label="Select your field(s)"
            multiSelect={false}
            listId="ab7a0321-e395-40c5-89d5-fad2b68fc6cd"
            onSelectionChanged={onFieldPickerChanged}
            showBlankOption={true}
        />
    );
};
export default FieldPickerCtr;

Breaking down the control

context

context={context}

Provides the SPFx context.

Required to access SharePoint APIs.

Without it, the control cannot retrieve fields.

includeHidden

includeHidden={false}

Excludes hidden/system fields.

This avoids showing things like:

• GUID
• FileRef
• ContentTypeId

Good for cleaner configuration.

includeReadOnly

includeReadOnly={false}

Excludes non-editable fields.

Useful when your logic should only use business fields.

label

label="Select your field(s)"

Simple UI label for whoever is configuring the component.

Usually admins.

multiSelect

multiSelect={false}

Only one field.

Useful when selecting:

• a sort field
• a filter field
• a display field

If true:

multiSelect={true}

you could configure multiple fields.

listId

listId="ab7a0321-e395-40c5-89d5-fad2b68fc6cd"

Defines which SharePoint list to inspect.

This is important because every list has its own schema.

onSelectionChanged

onSelectionChanged={onFieldPickerChanged}

Returns the selected field metadata.

Your code:

const onFieldPickerChanged = (fields: any | any[]) => {
  console.log("Fields:", fields);
};

Typical output:

{
  "id": "Status",
  "internalName": "Status",
  "title": "Status"
}

This is where the real value is.

Real-world usage

1. Property Pane configuration

Most common.

Admin selects:

Which field should this web part display?

FieldPicker stores:

InternalName = Status

Then:

item[selectedField.internalName]

2. Dynamic reporting web parts

Admin chooses:

• Group by field
• Filter field
• Sort field

No code changes required.

3. Generic dashboard builders

Imagine a reusable chart component.

Admin chooses:

X axis = Department
Y axis = Revenue

FieldPicker makes that possible.

4. SharePoint migration tools

Very useful when mapping fields between lists.

Especially in tools like ShareGate.

Important distinction: not for end users

Normal users should not choose SharePoint internal fields.

That would expose technical complexity.

Instead, end users should interact with:

• forms
• filters
• tables
• charts

FieldPicker belongs to:

• developers
• administrators
• advanced builders

That’s its true purpose.

Final thoughts

FieldPicker is not flashy.

It does not create visible business features.

But architecturally, it is one of the most useful controls in the PnP library.

It helps build:

• configurable web parts
• reusable components
• dynamic solutions
• schema-independent logic

Its real power is not what it shows.

Its real power is what it enables behind the scenes.

And for serious SPFx development, that makes it extremely valuable.