A custom Contentful app that provides a visual color picker for short text fields.
Instead of typing a color name or hex code, editors select from a row of color swatches.
The field stores the color name (key), while the UI displays the corresponding color.

• 🎨 Visual color selection via clickable swatches
• ♟ Support for a transparent color (checkerboard SVG pattern)
• 💬 Tooltips showing the color name on hover/focus
• 📝 Optional help text displayed under the swatches
• 🧩 Works as an Entry Field editor for Short text (Symbol) fields
• ⚙️ Colors defined per field via an instance parameter (colorsJson)
• 📦 Ready for use as a hosted app in Contentful
• 🧪 Basic unit tests for the field behavior

npm install

npm start

This will:

• Create or update the app definition in your Contentful space
• Start a local dev server with hot reload
• Allow you to use the app directly inside Contentful while developing

Make sure the app is installed and configured in the same space you are editing.

npm run build

This creates an optimized production build in the build/ directory.

npm run upload

The upload script will:

• Zip the contents of build/
• Create a new app bundle in Contentful
• Optionally activate that bundle for your app

Follow the CLI prompts to select:

• Organization
• App definition
• Whether to activate the new bundle

After this, Contentful will serve the app directly from the hosted bundle (no localhost required).

Open Apps → Manage apps → Contentful Color Selector and make sure the following is configured:

• Location: Entry field is enabled

• Instance parameters:

  • colorsJson (Short or Long text) – required
  • helpText (Short text) – optional

Example definition:

• ID: colorsJson
  Label: Colors JSON
  Type: Long text

• ID: helpText
  Label: Help text
  Type: Short text

Save the app configuration.

1. Go to Content model.

2. Open the content type you want to extend.

3. Add or edit a field of type Text → Short text (Symbol).

4. Go to the Appearance tab for this field.

5. Select the custom editor for this app (e.g. Contentful Color Selector).

6. In the instance parameters area for this field, configure:

   colorsJson (required)

   A JSON object mapping color names to hex codes:

   {
     "Transparent": "",
     "Black": "#000000",
     "Gray": "#808080",
     "Red": "#f05c5c",
     "Yellow": "#fff58a",
     "Mint": "#b8ffd5",
     "Lilac": "#e8d5ff"
   }

   • The key (e.g. "Red") is what gets stored in the field.
   • The value (e.g. "#f05c5c") is the visual color of the swatch.
   • An empty string ("") is treated as a transparent color and rendered with a checkerboard pattern.

   helpText (optional)

   A short string displayed under the row of swatches. For example:

   Select one of the predefined brand colors.
   

7. Save the content type.

• The field is a Short text field in Contentful.
• The app reads colorsJson from the instance parameters and builds a list of [name, hex] pairs.
• Each entry is rendered as a clickable circular swatch.
• When the user clicks a swatch:
  • The field value is set to the name of the color (the JSON key).
• For the special case where hex is an empty string:
  • The swatch is drawn with a transparent background and a checkerboard SVG pattern.

This approach:

• Keeps the stored value stable and easy to query/filter ("Red", "Gray", "Transparent", etc.)
• Allows the actual hex codes to be adjusted in Contentful without changing content values.
• Works well with frontend mapping (e.g. mapping "Red" to a design token or CSS variable).

To run the tests:

npm test

The tests cover:

• Rendering of the fallback message when colorsJson is not configured
• Rendering swatches from colorsJson
• Setting the field value when a swatch is clicked

• React + TypeScript
• Vite
• Contentful App SDK
• Forma 36 (Contentful design system)
• Vitest + @testing-library/react

src/
  App.tsx               # Main app component, selects location-specific component
  index.tsx             # Entry point
  locations/
    Field.tsx           # Color selector field editor

build/                  # Production build output (created by `npm run build`)
package.json
vite.config.mts
README.md

Ideas for future enhancements:

• Multiple rows or grouped palettes
• Support for different swatch sizes
• Displaying color names directly under each swatch
• Integration with design tokens or theme configuration
• Allowing per-environment palettes

Contributions or forks inside your own org/project are welcome. Adjust it freely to match your Contentful setup and design system.