@nouance/payload-better-fields-plugin
v1.4.1
Published
A Payload plugin that aims to provide improved fields for the admin panel
Downloads
7,520
Maintainers
Readme
Better fields plugin
This plugin aims to provide you with very specific and improved fields for the admin panel.
We've tried to keep styling as consistent as possible with the existing admin UI, however if there are any issues please report them!
Every field will come with its own usage instructions and structure. These are subject to change!
⚠️ Breaking changes 1.0 release ⚠️
All fields have had changes to standardise how the field parameters are structured. Field overrides will now be mandatory and come first across fields.
Payload compatibility
| Payload | Better fields | | ------- | ------------- | | 1.x | < 1.0 | | 2.x | > 1.0 |
Installation
yarn add @nouance/payload-better-fields-plugin
# OR
npm i @nouance/payload-better-fields-plugin
Fields
- Slug field
- Combo field
- Number field
- Pattern field
- Range field
- Colour Text field
- Telephone field
- Alert Box field
- Colour Picker field
- Date field
Styling
We've tried to re-use the internal components of Payload as much as possible. Where we can't we will re-use the CSS variables used in the core theme to ensure as much compatibility with user customisations.
If you want to further customise the CSS of these components, every component comes with a unique class wrapper in the format of bf<field-name>Wrapper
, eg bfPatternFieldWrapper
, to help you target these inputs consistently.
Slug field
Usage
import { CollectionConfig } from 'payload/types'
import { SlugField } from '@nouance/payload-better-fields-plugin'
const Examples: CollectionConfig = {
slug: 'examples',
admin: {
useAsTitle: 'title',
},
fields: [
{
name: 'title',
type: 'text',
},
...SlugField(
{
name: 'slug',
admin: {
position: 'sidebar',
},
},
{
useFields: ['title', 'subtitle'],
},
),
],
}
Options
The SlugField
accepts the following parameters
overrides
-TextField
required Textfield overridesconfig
useFields
-string[]
defaults to['title']
appendOnDuplication
-boolean
defaults tofalse
| Adds a validation hook that appends-1
to your slug to avoid conflicts (experimental)slugify
- Options to be passed to the slugify function
@default { lower: true, remove: /[*+~\/\\.()'"!?#\.,:@]/g }
checkbox
enable
-boolean
defaults totrue
| Enable or disable the checkbox fieldoverrides
-CheckboxField
| Checkbox field overrides
Here is a more full example:
...SlugField(
{
name: 'secondSlug',
admin: {
position: 'sidebar',
},
},
{
useFields: ['nested.heading'],
},
{
enable: true,
overrides: {
name: 'secondEdit',
},
},
)
Notes
index
and unique
are set to true by default
Combo field
Usage
import { CollectionConfig } from 'payload/types'
import { ComboField } from '@nouance/payload-better-fields-plugin'
const Examples: CollectionConfig = {
slug: 'examples',
admin: {
useAsTitle: 'fullName',
},
fields: [
{
type: 'row',
fields: [
{
name: 'firstName',
type: 'text',
},
{
name: 'lastName',
type: 'text',
},
],
},
...ComboField(['firstName', 'lastName'], { name: 'fullName' }),
],
}
Options
The ComboField
accepts the following parameters
overrides
-TextField
required for name attributefieldToUse
-string[]
requiredoptions
separator
-string
defaults to' '
initial
-string
The starting string value before all fields are concatenatedcallback
-(value: string) => string
You can apply a callback to modify each field value if you want to preprocess them
Number field
source | react-number-format NumericFormat
Usage
import { CollectionConfig } from 'payload/types'
import { NumberField } from '@nouance/payload-better-fields-plugin'
const Examples: CollectionConfig = {
slug: 'examples',
admin: {
useAsTitle: 'fullName',
},
fields: [
{
name: 'title',
type: 'text',
},
...NumberField(
{
name: 'price',
required: true,
},
{
prefix: '$ ',
suffix: ' %',
thousandSeparator: ',',
decimalScale: 2,
fixedDecimalScale: true,
},
),
],
}
Options
The NumberField
accepts the following parameters
overrides
-NumberField
required for name attributeformat
-NumericFormatProps
required, accepts props for NumericFormatcallback
- you can override the internal callback on the value, thevalue
will be a string so you need to handle the conversion to an int or float yourself via parseFloat
// example callback: (value) => parseFloat(value) + 20,
Pattern field
source | react-number-format PatternFormat
Usage
import { CollectionConfig } from 'payload/types'
import { PatternField } from '@nouance/payload-better-fields-plugin'
const Examples: CollectionConfig = {
slug: 'examples',
admin: {
useAsTitle: 'fullName',
},
fields: [
{
name: 'title',
type: 'text',
},
...PatternField(
{
name: 'telephone',
type: 'text',
required: false,
admin: {
placeholder: '% 20',
},
},
{
format: '+1 (###) #### ###',
prefix: '% ',
allowEmptyFormatting: true,
mask: '_',
},
),
],
}
Options
The PatternField
accepts the following parameters
overrides
-TextField
required for name attributeformat
-PatternFormatProps
required, accepts props for PatternFormatformat
required, input for the pattern to be appliedcallback
- you can override the internal callback on the value, thevalue
will be a string so you need to handle the conversion to an int or float yourself via parseFloat
// example callback: (value) => value + 'ID',
Notes
We recommend using a text field in Payload.
Range field
Usage
import { CollectionConfig } from 'payload/types'
import { RangeField } from '@nouance/payload-better-fields-plugin'
const Examples: CollectionConfig = {
slug: 'examples',
admin: {
useAsTitle: 'title',
},
fields: [
{
name: 'title',
type: 'text',
},
...RangeField(
{
name: 'groups',
},
{ min: 5, max: 200, step: 5 },
),
],
}
export default Examples
Options
The RangeField
accepts the following parameters
overrides
-NumberField
required for name attributeconfig
- requiredmin
-number
defaults to 1max
-number
defaults to 100step
-number
defaults to 1showPreview
-boolean
defaults to false, shows a preview box of the underlying selected value,n/a
for nullmarkers
-NumberMarker[]
array of markers to be visually set, accepts an optional label{ value: number, label?: string}[]
Colour Text field
Usage
import { CollectionConfig } from 'payload/types'
import { ColourTextField } from '@nouance/payload-better-fields-plugin'
const Examples: CollectionConfig = {
slug: 'examples',
admin: {
useAsTitle: 'title',
},
fields: [
{
name: 'title',
type: 'text',
},
...ColourTextField({
name: 'colour',
}),
],
}
export default Examples
Options
The ColourTextField
accepts the following parameters
overrides
-TextField
required for name attribute
Telephone field
source | react-phone-number-input
Usage
import { CollectionConfig } from 'payload/types'
import { TelephoneField } from '@nouance/payload-better-fields-plugin'
const Examples: CollectionConfig = {
slug: 'examples',
admin: {
useAsTitle: 'title',
},
fields: [
{
name: 'title',
type: 'text',
},
...TelephoneField({
name: 'telephone',
admin: {
placeholder: '+1 2133 734 253',
},
}),
],
}
export default Examples
Options
The TelephoneField
accepts the following parameters
overrides
-TextField
required forname
attributeconfig
-Config
optional, allows for overriding attributes in the phone fieldinternational
defaults totrue
| Forces international formattingdefaultCountry
accepts a 2-letter country code eg.'US'
| If defaultCountry is specified then the phone number can be input both in "international" format and "national" formatcountry
accepts a 2-letter country code eg.'US'
| If country is specified then the phone number can only be input in "national" (not "international") formatinitialValueFormat
If an initial value is passed, and initialValueFormat is "national", then the initial value is formatted in national formatwithCountryCallingCode
If country is specified and international property is true then the phone number can only be input in "international" format for that countrycountryCallingCodeEditable
smartCaret
When the user attempts to insert a digit somewhere in the middle of a phone number, the caret position is moved right before the next available digit skipping any punctuation in betweenuseNationalFormatForDefaultCountryValue
When defaultCountry is defined and the initial value corresponds to defaultCountry, then the value will be formatted as a national phone number by defaultcountrySelectProps
unicodeFlags
defaults tofalse
| Set totrue
to render Unicode flag icons instead of SVG images
Alert Box field
Usage
import { CollectionConfig } from 'payload/types'
import { AlertBoxField } from '@nouance/payload-better-fields-plugin'
const Examples: CollectionConfig = {
slug: 'examples',
admin: {
useAsTitle: 'title',
},
fields: [
{
name: 'title',
type: 'text',
},
...AlertBoxField(
{
name: 'alert',
},
{
type: 'info',
message: 'Please be aware that the title is required for the mobile app.',
},
),
],
}
export default Examples
Options
The AlertBoxField
accepts the following parameters
overrides
-UIField
required forname
attributeconfig
-Config
requiredtype
- a selection ofinfo
|alert
|error
which come with different stylesmessage
- required stringclassName
- optional string to help you style individual alerts bettericon
- optional, default is enabledenable
- boolean, turn off the iconElement
- React component to override the provided icon
If you want to make this field appear conditionally, you should use the field's admin conditional config as provided by Payload.
Colour Picker field
Usage
import { CollectionConfig } from 'payload/types'
import { ColourPickerField } from '@nouance/payload-better-fields-plugin'
const Examples: CollectionConfig = {
slug: 'examples',
admin: {
useAsTitle: 'title',
},
fields: [
{
name: 'title',
type: 'text',
},
...ColourPickerField(
{
name: 'backgroundColour',
required: true,
},
{
type: 'hslA',
},
),
],
}
export default Examples
Options
The ColourPickerField
accepts the following parameters
overrides
-TextField
required forname
attributeconfig
-Config
requiredtype
- defaults tohex
, a selection ofhex
|hexA
|rgb
|rgbA
|hsl
|hslA
expanded
- optional boolean, controls if the selector is visible by defaultshowPreview
- optional boolean
Date field
The goal of this field is to help with management of timezones.
Usage
import { CollectionConfig } from 'payload/types'
import { DateField } from '@nouance/payload-better-fields-plugin'
const Examples: CollectionConfig = {
slug: 'examples',
admin: {
useAsTitle: 'title',
},
fields: [
{
name: 'title',
type: 'text',
},
...DateField({
name: 'date',
admin: {
date: {
pickerAppearance: 'dayAndTime',
},
},
}),
],
}
export default Examples
Options
The DateField
accepts the following parameters
overrides
-DateField
required forname
attributetimezone
-Timezone
optionalenabled
- defaults totrue
timezones
- optional list of timezones to customise available optionsoverrides
-SelectField
required forname
attribute
Contributing
For development purposes, there is a full working example of how this plugin might be used in the dev directory of this repo.
git clone [email protected]:NouanceLabs/payload-better-fields-plugin.git \
cd payload-better-fields-plugin && yarn \
cd demo && yarn \
cp .env.example .env \
vim .env \ # add your payload details
yarn dev
Contributors
Thanks to the following people for contributing code to this plugin