How to build niche filters and badges with custom fields

Turn a board's job and company custom fields into filter dropdowns and listing badges.

Custom fields let a board describe what matters in its niche: whether a role is identified for a particular community, whether an employer sponsors visas, which clearance a job needs. This recipe turns two of them into filter dropdowns on the job listing page and badges on each job card.

Boards built from the latest starter already add every public single select, multi-select and yes-or-no field to the All filters sheet. Follow this recipe when you want a different layout, such as dropdowns in the main search bar, or when you build the listing page yourself.

The running example is a board for Aboriginal employment in Australia. It has one job field and one company field:

Field	Belongs to	Type	Options
Opportunity type	Job	Single choice	Aboriginal Identified, Aboriginal Sector, Mainstream (Aboriginal applicants encouraged)
Employer type	Company	Single select	Aboriginal Community Controlled Organisation, Aboriginal Owned Business, Government Sector, Corporate Sector, Health, Private

Use a job field for something that can differ between two jobs at the same employer, such as whether a particular role is identified. Use a company field for something true of the employer, such as its ownership. A company field is set once per company and applies to every job that company posts. Use the wording your community and your board already use for these categories; the labels above follow one board's choices.

Before you begin

Build the listing route from Build a job listing page. This recipe adds a search function beside its loadJobs.
You need dashboard access that can manage settings on the board.

Set up the fields in the dashboard

The operator creates both fields once. The frontend reads their definitions at runtime, so a new option shows up without a code change.

The job field. Open Settings → Job form, scroll to Custom fields, and click Add field. Name it "Opportunity type", choose Dropdown (single choice), and add the three options. Every posting form on the board then asks for it.

The company field. Open Settings → Company profile, then in Custom fields click Add field. Name it "Employer type", choose Single select, and add the six options. Turn on Show on public profile: only public fields can be filtered or shown. Turn on Profile owner can edit if employers should choose their own type; leave it off if your team verifies it.

Each option has a label, which visitors see, and a key, which is what gets stored and filtered on. Keys are fixed once saved, so renaming a label later never breaks a saved URL. This recipe assumes keys like these:

Field key	Option keys
`opportunity_type`	`identified`, `sector`, `mainstream`
`employer_type`	`acco`, `aboriginal_owned`, `government`, `corporate`, `health`, `private`

A job field key and a company field key may be the same word. Job search keeps them apart, so type on a job never matches type on a company.

Read the definitions

Job field definitions come from the board context. Company field definitions come from board.profileFields, which returns public fields only, so a private company field can never become a filter option.

1// src/lib/niche-fields.ts
2import { board } from './cavuno';
3
4export async function loadNicheFields() {
5  const [context, companyFields] = await Promise.all([
6    board.context(),
7    board.profileFields.retrieve('company'),
8  ]);
9
10  const opportunityType = context.customFields.job.find(
11    (field) => field.key === 'opportunity_type',
12  );
13  const employerType = companyFields.definitions.find(
14    (field) => field.key === 'employer_type',
15  );
16
17  return { language: context.language, opportunityType, employerType };
18}

If either field is missing, the operator has deleted it or made it private. Hide that dropdown instead of rendering an empty one.

Keep option keys in the URL

The URL holds option keys, not labels, so a shared link keeps working after a label is reworded or translated. Accept only keys the current definition offers; anything else from a hand-typed URL is dropped.

1// src/lib/niche-filters.ts
2type Option = { key: string; label: string };
3
4export function selectedOption(
5  raw: unknown,
6  options: readonly Option[] | undefined,
7): string | undefined {
8  if (typeof raw !== 'string') return undefined;
9  return options?.some((option) => option.key === raw) ? raw : undefined;
10}

A visitor who picks "Aboriginal Community Controlled Organisation" produces /jobs?employer=acco. Choose URL parameter names that suit your routes; the field keys only matter in the search body.

Render the dropdowns

Each dropdown lists the definition's options in the operator's order, shows the label, and submits the key. Keep a visible label on every control.

tsx

1const fields = await loadNicheFields();
2const opportunity = selectedOption(
3  searchParams.opportunity,
4  fields.opportunityType?.options,
5);
6const employer = selectedOption(
7  searchParams.employer,
8  fields.employerType?.options,
9);
10
11return (
12  <form method="get" action="/jobs">
13    {fields.opportunityType ? (
14      <label>
15        {fields.opportunityType.label}
16        <select name="opportunity" defaultValue={opportunity ?? ''}>
17          <option value="">All</option>
18          {fields.opportunityType.options?.map((option) => (
19            <option key={option.key} value={option.key}>
20              {option.label}
21            </option>
22          ))}
23        </select>
24      </label>
25    ) : null}
26    {fields.employerType ? (
27      <label>
28        {fields.employerType.label}
29        <select name="employer" defaultValue={employer ?? ''}>
30          <option value="">All</option>
31          {fields.employerType.options?.map((option) => (
32            <option key={option.key} value={option.key}>
33              {option.label}
34            </option>
35          ))}
36        </select>
37      </label>
38    ) : null}
39    <button type="submit">Show jobs</button>
40  </form>
41);

"All" is application copy. Translate it with the rest of your interface chrome.

Search with both filters

Send the job field under filters.customFields and the company field under filters.companyCustomFields. Both take a list of clauses with a field key and the accepted values. Clauses are AND-matched and the values inside one clause are OR-matched, so a multi-select dropdown sends one clause with several values.

1// src/lib/load-jobs.ts
2import { board } from './cavuno';
3
4export async function loadNicheJobs(search: {
5  q?: string;
6  opportunity?: string;
7  employer?: string;
8}) {
9  return board.jobs.search({
10    query: search.q,
11    filters: {
12      customFields: search.opportunity
13        ? [{ key: 'opportunity_type', values: [search.opportunity] }]
14        : undefined,
15      companyCustomFields: search.employer
16        ? [{ key: 'employer_type', values: [search.employer] }]
17        : undefined,
18    },
19    limit: 20,
20  });
21}

/jobs?opportunity=identified&employer=acco returns identified roles at community controlled organisations. Job search filters on custom fields in board.jobs.search only; board.jobs.list does not take them.

Each list accepts up to 10 clauses of up to 10 values. A select value is an option key, a yes-or-no field takes true or false, and a number field takes a number. A key that is unknown or private, or an option key the field does not define, is rejected with invalid_filter. That usually means a stale URL after the operator changed the field, so drop the parameter and search again rather than showing an error page.

When a company's employer type changes, its jobs are re-indexed automatically, usually within seconds. You do not need to invalidate anything.

Show badges on job cards

Job cards carry the card-safe custom values (select, yes-or-no, and number fields) for the job in customFieldValues and for its company in company.customFieldValues, keyed by field key. Resolve each stored option key to its current label through the same definitions the dropdowns use.

1type Definition = {
2  key: string;
3  options?: { key: string; label: string }[];
4};
5
6function optionLabel(
7  definition: Definition | undefined,
8  value: unknown,
9): string | null {
10  if (!definition || typeof value !== 'string') return null;
11  return (
12    definition.options?.find((option) => option.key === value)?.label ?? null
13  );
14}
15
16const page = await loadNicheJobs(searchParams);
17
18const cards = page.data.map((job) => ({
19  ...job,
20  badges: [
21    optionLabel(
22      fields.opportunityType,
23      job.customFieldValues.opportunity_type,
24    ),
25    optionLabel(
26      fields.employerType,
27      job.company?.customFieldValues.employer_type,
28    ),
29  ].filter((label): label is string => label !== null),
30}));

A value whose option was removed resolves to no label, so the badge disappears instead of showing a raw key. Style badges as secondary information: the job title stays the strongest text on the card.

Verify the recipe

In the dashboard, set the employer type on two companies that each have published jobs, one to acco and one to government.
Open /jobs?employer=acco and confirm only the first company's jobs appear, each with an "Aboriginal Community Controlled Organisation" badge.
Change the first company to government, wait a few seconds, reload, and confirm its jobs have moved to /jobs?employer=government.
Combine both filters and confirm the result matches both.
Open /jobs?employer=unknown and confirm the page ignores the parameter instead of failing.
Make the company field private in Settings and confirm the dropdown and its badges disappear.

See the Jobs reference for the full search body and the Profile fields reference for company definitions.