> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Picklists
> Manage all organization-wide dropdown values with export, import, and template library support; edit individual picklist items, labels, and ordering.
Administrators can manage all picklists at `/settings/picklists`. This route renders `PicklistsPage` from `src/platform/picklists/pages/PicklistsPage.tsx` with no explicit route-level permission wrapper.
## Overview
The Picklists page lists all picklists available to the organization using `PicklistsTable`. It is organized in two tabs: **Picklists** (the main list) and a **Templates** library (`PicklistTemplateLibrary`). Users with `pf.picklists.admin` permission can export picklists via `PicklistExportDialog`, import picklists via `PicklistImportDialog`, and apply templates from the template library (which pre-populates the import dialog with `templateRecords`). Selecting a picklist row navigates to `/settings/picklists/:id` for detail view and editing.
## Who it's for
Access follows your organization's role and module configuration. Admin actions (export, import) require `pf.picklists.admin` (checked at component level).
## Before you start
* You must be signed in.
## Steps
1. Navigate to **Settings > Picklists** (`/settings/picklists`).
2. Browse the list of picklists in the **Picklists** tab.
3. Select a picklist to view its details and items.
4. Use **Export** to download picklist definitions.
5. Use **Import** to upload picklist definitions from a file.
6. Switch to the **Templates** tab to browse and apply predefined picklist templates.
## Key concepts
**Picklist** — A named list of selectable values used to populate dropdown fields across forms and data objects throughout the platform.
**Template library** — Pre-built picklist collections that can be applied to an organization in bulk to accelerate setup.
## Editing a picklist
Administrators can view and edit a specific picklist at `/settings/picklists/:id`. This route renders `PicklistDetailPage` from `src/platform/picklists/pages/PicklistDetailPage.tsx` with no explicit route-level permission wrapper.
The page displays the metadata and items for a specific picklist identified by its `:id` URL parameter. Picklist data is loaded via `usePicklist()`. Items are managed via `PicklistItemsEditor`. The `PicklistForm` dialog allows editing the picklist's name, label, and description. A `SystemPicklistBanner` is shown for picklists where `is_system = true` and `organization_id = null` to indicate they are read-only global definitions. Users with `pf.picklists.admin` permission can duplicate a system picklist to their organization via `duplicatePicklistToOrg()`. Dynamic breadcrumb labels are set via `useBreadcrumbLabel()`.
Editing actions require `pf.picklists.admin` (checked at component level via `useHasPermission`).
1. Navigate to **Settings > Picklists** and select a picklist, or go directly to `/settings/picklists/:id`.
2. Review the picklist items and their display order.
3. To edit metadata, select the edit button to open `PicklistForm`.
4. Add, reorder, or remove items in the `PicklistItemsEditor`.
5. If viewing a system picklist, use **Duplicate to Org** to create an editable copy.
**System picklist** — A global, platform-managed picklist (`is_system = true`, `organization_id = null`). These are read-only; to customize, duplicate to your organization.
**Organization picklist** — A tenant-specific picklist that can be freely edited.
## Locked picklists
Some picklists mirror a database constraint or a regulated code set (for example, consent types or payment methods). They are shipped with a value-set lock so a tenant edit can't silently break a database insert or a regulated workflow.
On a locked picklist the detail page shows an explanatory alert and disables **Add item**, **Delete**, and **Deactivate**. You can still edit:
* Item **label**, **color**, and **display order**
* The new **Aliases** field (see below)
To change the underlying value set on a locked picklist, the platform team ships a migration that updates both the database constraint and the seed.
The classification model — Tier A workflow states, Tier B org vocabulary, Tier C constraint-mirrored — is documented in [ADR-027](/architecture/decisions/ADR-027-picklist-naming-and-tier-classification).
## Aliases
Each picklist item has an **Aliases** field for alternate strings that should resolve to this value. Aliases are used by the importer's value-mapping step to match incoming source values (for example, mapping `"ACH"` to a Payment Method item whose value is `eft`). Aliases are case-insensitive and never change the stored value — only the mapping suggestion.
Add one alias per line in the item editor. Aliases are available on both editable and locked picklists.
## Naming convention
New system picklists use a dot-namespace name of the form `{core}.{domain}.{field}` — for example, `cl.notes.type`, `pm.payments.method`, `lo.meetings.type`. Older flat names (such as `hr_employment_status`) are kept as-is to avoid breaking saved data. When you create an organization picklist in the form, the name must match `^[a-z0-9_]+(\.[a-z0-9_]+)*$`.
## Related
Platform Foundation overview.
Documentation coverage and governance.
This page documents shipped product behavior. It is not medical, legal, or
billing advice. Verify against your organization's policies and applicable
regulations before using it for clinical, compliance, or billing decisions.
Protected health information (PHI) shown in the product is governed by your
tenant's access controls and is never exposed in this documentation.
* src/routes/platform.tsx
* src/platform/picklists/pages/PicklistsPage.tsx
* src/platform/picklists/components/PicklistsTable.tsx
* src/platform/picklists/pages/PicklistDetailPage.tsx
* src/platform/picklists/hooks/usePicklist.ts