Brazilian Fields and Widgets for Plone 🚀

Dexterity fields and Volto widgets for data used in Brazilian projects.

Field	Holds	Shown as
CEP 🏠	A postal code	01310-100
CNPJ 🏢	The registration number of a company	11.222.333/0001-81
CPF 🆔	The registration number of a person	377.313.354-53
Estados 📍	A state, or the Federal District	São Paulo
Telefone 📞	A phone number, landline or mobile	(11)98765-4321

The backend fields validate every value stored in them. The Volto widgets format each value while the editor types it, and warn about a wrong value before the form is sent.

📖 Read the documentation at plonegovbr.github.io/brfieldsandwidgets, and browse the widgets in Storybook.

Packages 📦

This monorepo hosts two packages, released together:

• backend/: the Python package plonegovbr.brfields, with the Dexterity fields.
• frontend/packages/volto-brwidgets/: the npm package @plonegovbr/volto-brwidgets, with the Volto widgets.

Compatibility ✅

Plone	6.1 and 6.2
Python	3.11 to 3.14
Volto	19, developed against 19.5.1

Use the fields 🧩

from plone.supermodel import model
from plonegovbr.brfields.fields import CNPJ
from plonegovbr.brfields.fields import CPF


class IEmpresa(model.Schema):
    cnpj = CNPJ(title="CNPJ")
    responsavel = CPF(title="CPF do responsável", required=False)

Then add @plonegovbr/volto-brwidgets to your Volto project's add-ons. The installation guides have the details.

Development 💻

Prerequisites

• uv 🐍 (Python dependency manager)
• Node.js 24 🟩
• pnpm 🧶 (JavaScript package manager)
• Docker 🐳 (optional, for the container stack)

Installation 🔧

git clone git@github.com:plonegovbr/brfieldsandwidgets.git
cd brfieldsandwidgets
make install

This also creates a site with a demo content type using every field.

Fire up the servers 🔥

Start the Backend (Plone) at http://localhost:8080/:

make backend-start

In a new terminal, start the Frontend (Volto) at http://localhost:3000/:

make frontend-start

Tests and code quality 🧐

make test
make format
make lint

Storybook and documentation 📚

make storybook-start
make docs-live

Running with Docker 🐳

The stack builds both images from this repository, and serves them behind Traefik at http://brfieldsandwidgets.localhost:

make stack-create-site
make stack-start

Contributing 🤝

Contributions are welcome! Check out:

• Source Code 💻
• Issue Tracker 🐛
• Contributing guide 📝

Every pull request requires a change log entry, in one of these folders:

• repository: news
• backend: backend/news
• frontend: frontend/packages/volto-brwidgets/news

Credits & Acknowledgements 🙏

This package is developed and maintained by the PloneGov-BR community ❤️.