|
1 | 1 | # Payload Custom Components Example |
2 | 2 |
|
3 | | -This example demonstrates how to use Custom Components in [Payload](https://github.com/payloadcms/payload) Admin Panel. This example includes custom components for every field type available in Payload, including both server and client components. It also includes custom views, custom nav links, and more. |
| 3 | +This example demonstrates how to use Custom Components in the [Payload](https://github.com/payloadcms/payload) Admin Panel. Custom components allow you to extend Payload by providing custom UI elements for fields, collections, and views. This example covers custom components for every field type available in Payload, including both server and client components. |
4 | 4 |
|
5 | 5 | ## Quick Start |
6 | 6 |
|
7 | | -To spin up this example locally, follow these steps: |
| 7 | +To spin up this example locally, follow the steps below: |
8 | 8 |
|
9 | 9 | 1. Clone this repo |
10 | | -1. `cd` into this directory and run `pnpm i --ignore-workspace`\*, `yarn`, or `npm install` |
| 10 | +1. Navigate into the project directory and install dependencies using your preferred package manager: |
11 | 11 |
|
12 | | - > \*If you are running using pnpm within the Payload Monorepo, the `--ignore-workspace` flag is needed so that pnpm generates a lockfile in this example's directory despite the fact that one exists in root. |
| 12 | +- `pnpm i --ignore-workspace`\*, `yarn`, or `npm install` |
13 | 13 |
|
14 | | -1. `pnpm dev`, `yarn dev` or `npm run dev` to start the server |
15 | | - - Press `y` when prompted to seed the database |
16 | | -1. `open http://localhost:3000` to access the home page |
17 | | -1. `open http://localhost:3000/admin` to access the admin panel |
18 | | - - Login with email `[email protected]` and password `demo` |
| 14 | +> \*NOTE: The --ignore-workspace flag is needed if you are running this example within the Payload monorepo to avoid workspace conflicts. |
| 15 | +
|
| 16 | +1. Start the server: |
| 17 | + - Depending on your package manager, run `pnpm dev`, `yarn dev` or `npm run dev` |
| 18 | + - When prompted, type `y` then `enter` to seed the database with sample data |
| 19 | +1. Access the application: |
| 20 | + - Open your browser and navigate to `http://localhost:3000` to access the homepage. |
| 21 | + - Open `http://localhost:3000/admin` to access the admin panel. |
| 22 | +1. Login: |
| 23 | + |
| 24 | +- Use the following credentials to log into the admin panel: |
| 25 | + > `Email: [email protected]` > `Password: demo` |
19 | 26 |
|
20 | 27 | ## How it works |
21 | 28 |
|
22 | 29 | ### Collections |
23 | 30 |
|
24 | | -See the [Collections](https://payloadcms.com/docs/configuration/collections) docs for details on how to extend any of this functionality. |
| 31 | +[Collections](https://payloadcms.com/docs/configuration/collections) in Payload allow you to define structured content types. This example includes multiple collections, with a focus on: |
25 | 32 |
|
26 | 33 | - #### Users |
27 | 34 |
|
28 | | - The `users` collection is auth-enabled which provides access to the admin panel. |
| 35 | + The `users` collection is **auth-enabled**, providing access to the admin panel and enabling user authentication. This collection shows how to implement a basic user collection with authentication. |
29 | 36 |
|
30 | | - For additional help with authentication, see the official [Auth Example](https://github.com/payloadcms/payload/tree/main/examples/auth/cms#readme) or the [Authentication](https://payloadcms.com/docs/authentication/overview#authentication-overview) docs. |
| 37 | + - For more details on setting up authentication, checkout the [Auth Example](https://github.com/payloadcms/payload/tree/main/examples/auth/cms#readme) and the [Authentication Overview](https://payloadcms.com/docs/authentication/overview#authentication-overview). |
31 | 38 |
|
32 | 39 | - #### Fields |
33 | 40 |
|
34 | | - The `fields` collection contains every field type available in Payload, each with custom components filled in every available "slot", i.e. `admin.components.Field`, `admin.components.Label`, etc. There are two of every field, one for server components, and the other for client components. This pattern shows how to use custom components in both environments, no matter which field type you are using. |
| 41 | + The `fields` collection demonstrates all the **field types** available in Payload, each one configured with custom components. This includes every available "slot" for custom components (e.g., `admin.components.Field`, `admin.components.Label`, `admin.components.Input`, etc.). For each field type, two examples are provided: one using **server-side components** and the other using **client-side components**. This pattern illustrates how to customize both types of components across different field types. |
| 42 | + |
| 43 | + - **Custom Field Components**: Custom components allow you to tailor the UI and behavior of the admin panel fields. This can be useful for implementing complex interactions, custom validation, or UI enhancements. For example, you might use a custom component to replace a simple text input with a date picker or a rich text editor. |
35 | 44 |
|
36 | 45 | - #### Views |
37 | 46 |
|
38 | | - The `views` collection demonstrates how to add collection-level views, including the default view and custom tabs. |
| 47 | + The `views` collection demonstrates how to create **collection-level views**, such as custom tabs or layout configurations. This is where you can modify how data is displayed in the admin panel beyond the default list and edit views. Custom views give you full control over how content is presented to users. |
39 | 48 |
|
40 | 49 | - #### Root Views |
41 | 50 |
|
42 | | - The `root-views` collection demonstrates how to add a root document-level view to the admin panel. |
| 51 | + The `root-views` collection shows how to implement **root-level views** in the admin panel. These views can be used to modify the global admin interface, adding custom sections or settings that appear outside of collections. |
| 52 | + |
| 53 | +## Troubleshooting |
| 54 | + |
| 55 | +If you encounter any issues during setup or while running the example, here are a few things to try: |
| 56 | + |
| 57 | +- **Missing dependencies**: If you see errors related to missing packages, try deleting the `node_modules` folder and the lockfile (`package-lock.json` or `pnpm-lock.yaml`), then rerun `npm install` or `pnpm i`. |
| 58 | + |
| 59 | +- **Port conflicts**: If the development server isn't starting, ensure that port `3000` isn't being used by another process. You can change the port by modifying the `package.json` file or setting the `PORT` environment variable. |
| 60 | + |
| 61 | +- **Seed data issues**: If the database seeding fails, try clearing the database and then rerun the seeding process. |
43 | 62 |
|
44 | 63 | ## Questions |
45 | 64 |
|
46 | 65 | If you have any issues or questions, reach out to us on [Discord](https://discord.com/invite/payload) or start a [GitHub discussion](https://github.com/payloadcms/payload/discussions). |
| 66 | + |
| 67 | +For more detailed documentation on how to extend and customize Payload, check out the full [Payload documentation](https://payloadcms.com/docs). |
0 commit comments