Skip to Content
BBRICKSv0.7.4
BlocksGroups

GroupForm

The New group / Edit group modal body: a name (required, 40 characters, unique) and the members picker (at least one for a new group; an edited group may be emptied). Errors show under their field and focus moves to the first one; nothing is sent until both hold.

import { GroupForm } from '@ergasti/bricks';

Examples

Create or edit a group

A name (checked for blanks and against takenNames) and the members; the form reports a GroupFormValue. In create mode it starts empty.

Code
import { GroupForm } from '@ergasti/bricks';
import { blocksData } from './sample-data';

function Edit() {
  const g = blocksData.GROUPS[0];
  return (
    <div style={{ maxWidth: 560 }}>
      <GroupForm mode="edit" initial={{ name: g.name, memberIds: g.members.map((m) => m.id) }} people={blocksData.MINE} takenNames={['TikTok first', 'New this month']} onSubmit={() => {}} onCancel={() => {}} />
    </div>
  );
}

Saving with an error

saving disables the buttons; error is the server's message.

Code
import { GroupForm } from '@ergasti/bricks';
import { blocksData } from './sample-data';

function Create() {
  return (
    <div style={{ maxWidth: 560 }}>
      <GroupForm mode="create" people={blocksData.MINE.slice(0, 5)} error="We could not save the group. Try again." onSubmit={() => {}} onCancel={() => {}} />
    </div>
  );
}

Saving

saving locks the buttons while the group is saved; pickerLabels renames words in the members picker inside the form.

Code
import { GroupForm } from '@ergasti/bricks';
import { blocksData } from './sample-data';

function Saving() {
  return (
    <div style={{ maxWidth: 560 }}>
      <GroupForm mode="create" initial={{ name: 'Ramadan picks', memberIds: [9] }} people={blocksData.MINE.slice(0, 5)} saving pickerLabels={{ legend: 'Creators in this group' }} onSubmit={() => {}} onCancel={() => {}} />
    </div>
  );
}

Server errors and an emptied group

fieldErrors puts the server's 422 on the name (name) and the picker (members, member_ids…); in edit mode a group may be saved with no members (rename it for next season), while create still needs one.

Code
import { GroupForm } from '@ergasti/bricks';
import { blocksData } from './sample-data';

function ServerErrorsAndEmpty() {
  return (
    <div style={{ maxWidth: 560 }}>
      <GroupForm mode="edit" initial={{ name: 'Ramadan stars', memberIds: [] }} people={blocksData.MINE} onSubmit={() => {}} onCancel={() => {}}
        fieldErrors={{ name: 'A group with this name already exists.' }} />
    </div>
  );
}

Props

Prop

Type

Labels

Every word this component draws, in both languages. Override one per component and language with BricksProvider labels under the key groupForm, or with the component's own prop where it has one. A {name} is a value the component fills in.

groupForm
KeyEnglishArabic
nameGroup nameاسم المجموعة
namePlaceholdere.g. Ramadan starsمثلاً نجوم رمضان
nameEmptyGive the group a nameاكتب اسم للمجموعة
nameTakenA group with this name already existsفيه مجموعة تانية بنفس الاسم
noMembersPick at least one creatorاختار صانع محتوى واحد على الأقل
cancelCancelإلغاء
createCreate groupاعمل المجموعة
saveSaveاحفظ
savingSaving…جاري الحفظ…

Design guidance

How the BRICKS design system uses GroupForm. Written in docs/content/components/GroupForm.md; the props above are read from the code, which wins where the two disagree.

The New group / Edit group modal body: a required, unique group name and a searchable members picker, with Cancel and Create group / Save; put it inside a Modal.

It is the mock's groupForm() modal on Brand › Creators › Groups (the mock's own version throws before it shows; this block does not copy that defect). It validates on submit: the name is required, at most 40 characters and different from other groups (any case); a new group needs at least one creator, an edited group may be emptied. Errors show under their field and focus moves to the first one; nothing is sent until both hold. The server's 422 field errors (fieldErrors) land on the same fields.

Anatomy

  1. Form: form.kit-blk-form (noValidate).
  2. Name: FormField "Group name", input maxLength=40, placeholder "e.g. Ramadan stars".
  3. Members: MembersPicker (legend with live count, search, checkbox list).
  4. Error: p.kit-blk-err[role=alert] for error.
  5. Actions: end-aligned "Cancel" and rasp "Create group" / "Save" ("Saving…").

Variants

modeSubmit labelMembers rule
'create'"Create group"At least one creator.
'edit'"Save"May be empty.

States

StateTrigger
Empty namesubmit with blank name: "Give the group a name", focus on name.
Taken namematches takenNames: "A group with this name already exists".
No members (create)"Pick at least one creator", focus on the search.
Server field errorsfieldErrors.name; members / member_ids… / creator_ids… on the picker; cleared on next send, focus moves once.
Server errorerror: alert above the buttons.
Savingsaving: both buttons disabled, "Saving…".

Usage

<Modal open title={mode === 'create' ? 'New group' : 'Edit group'} onClose={close}>
  <GroupForm mode={mode} people={creators} takenNames={groups.filter((g) => g.id !== editing?.id).map((g) => g.name)}
    initial={editing ? { name: editing.name, memberIds: editing.memberIds } : undefined}
    onSubmit={(v) => save.run(v)} onCancel={close}
    saving={save.pending} error={save.error?.message} fieldErrors={save.error?.fields} />
</Modal>

Where it appears

  • Brand › Creators › Groups › "+ New group" and the group drawer's Edit (groupForm() modal) (BrandCreators).

Guidelines

Do

  • Pass takenNames without the group being edited.
  • Close the modal and toast "Group saved" on success.

Don't

  • Don't add your own footer; the form has its buttons.

RTL and Arabic

  • Mirrors. Arabic: "اسم المجموعة", "اعمل المجموعة", "اكتب اسم للمجموعة".

Tokens

--line, --card, --rasp, --focus-ring-field, --bad, --rasp-50, --ink-3.

Accessibility

  • Labels via FormField; the picker is a fieldset with a live count.
  • Focus moves to the first invalid field, so its error is read with it (aria-describedby). The server error line is role="alert" and mounts with its text: most screen readers read it, but do not rely on that alone.

Found in the source

  • Roles in the markup: alert.
  • It moves focus in code.

Read from the component's source and tests. See Accessibility for the patterns the library follows.

See also: Button · useLanguage · CommissionInput · CommissionRate · GroupCard · GroupCommissionPill

Source

src/blocks/groups/GroupForm.tsx (line 68) on GitHub.

On this page