How the PersonalInfo Form Rendered --- KeyCloakify
· 13 min read
How the Form is Rendered
- Component Structure:
- The
UserProfileFieldscomponent is the main entry point, receiving props liket(translation function),form(React Hook Form instance),userProfileMetadata(attribute metadata), and others. - It renders a
ScrollFormcomponent, which takes asectionsprop to display grouped form fields.
- The
- Grouping Attributes:
- Logic: Inside
UserProfileFields,groupsWithAttributesis computed usinguseMemo:- If
userProfileMetadata.attributesis empty, it returns an empty array. - Filters attributes based on
hideReadOnly(excludes read-only fields iftrue). - Groups attributes by their
groupproperty, including an "ungrouped" category ({ name: undefined }) for attributes without a group. - Result: An array of
GroupWithAttributesobjects, each containing agroupand itsattributes.
- If
- Outcome: Only groups with attributes are rendered (filtered by
.filter((group) => group.attributes.length > 0)).
- Logic: Inside
- Rendering Sections:
- ScrollForm: The
ScrollFormcomponent receivessections, where each section is an object with:title: Derived fromgroup.displayHeaderorgroup.name, falling back tot("general").panel: A<div className="space-y-4">containing:- Optional group description (
<p>withpb-6 text-gray-700) ifgroup.displayDescriptionexists. - A list of
FormFieldcomponents, one per attribute in the group.
- Optional group description (
- Rendering:
ScrollFormlikely renders these sections as collapsible or navigable panels (exact behavior depends onScrollFormimplementation, not shown here).
- ScrollForm: The
- FormField Rendering:
- Logic: The
FormFieldcomponent determines how each attribute is rendered:- Special Case: If
attribute.name === "locale", it renders aLocaleSelector. - General Case: Otherwise, it selects a component from
FIELDSbased oninputType:inputTypeis computed bydetermineInputType(see below).- If
attribute.multivaluedor the value is multi-valued (isMultiValue), it defaults toMultiInputComponent. - Otherwise, it uses the mapped component from
FIELDS(e.g.,TextComponentfor"text",SelectComponentfor"select").
- Special Case: If
- Component Props: Each
FIELDScomponent receivest,form,inputType,attribute, andrenderer. - Outcome: Each attribute is rendered as a form field (e.g., text input, select dropdown) based on its metadata.
- Logic: The
- Field Types:
- Mapping: The
FIELDSobject mapsInputTypeto components:"text","html5-*"→TextComponent."textarea"→TextAreaComponent."select","multiselect"→SelectComponent."select-radiobuttons","multiselect-checkboxes"→OptionComponent."multi-input"→MultiInputComponent.
- Dynamic Selection:
determineInputTypechecks:- Root attributes (
username,firstName, etc.) →"text". attribute.annotations?.inputTypeif valid (e.g.,"select","textarea").- Default:
"text".
- Root attributes (
- Mapping: The
- Visual Layout:
- TailwindCSS:
<div className="space-y-4">adds vertical spacing between fields;<p className="pb-6 text-gray-700">styles group descriptions. - Result: A scrollable form with sections, each containing a group title, optional description, and a list of input fields.
- TailwindCSS:
1. Form Rendering
The UserProfileFields component is responsible for rendering the form. Here's how it works:
Step 1: Group Attributes
- The
userProfileMetadataobject contains metadata about the user profile, including attributes and groups. - The
groupsWithAttributesarray is created by grouping attributes based on theirgroupproperty. If an attribute doesn't belong to any group, it's placed in a default group.
const groupsWithAttributes = useMemo(() => {
if (!userProfileMetadata.attributes) {
return [];
}
const attributes = hideReadOnly
? userProfileMetadata.attributes.filter(({ readOnly }) => !readOnly)
: userProfileMetadata.attributes;
return [
{ name: undefined }, // Default group for attributes without a group
...(userProfileMetadata.groups ?? []),
].map<GroupWithAttributes>((group) => ({
group,
attributes: attributes.filter(
(attribute) => attribute.group === group.name,
),
}));
}, [hideReadOnly, userProfileMetadata.groups, userProfileMetadata.attributes]);
Step 2: Render the Form
- The
ScrollFormcomponent is used to render the form sections. Each section corresponds to a group of attributes. - For each group, the
titleis derived from the group'sdisplayHeaderor a fallback (e.g., "general"). - The
panelcontains the form fields for the group's attributes.
return (
<ScrollForm
label={t("jumpToSection")}
sections={groupsWithAttributes
.filter((group) => group.attributes.length > 0)
.map(({ group, attributes }) => ({
title: label(t, group.displayHeader, group.name) || t("general"),
panel: (
<div className="space-y-4">
{group.displayDescription && (
<p className="pb-6 text-gray-700">
{label(t, group.displayDescription, "")}
</p>
)}
{attributes.map((attribute) => (
<FormField
key={attribute.name}
t={t}
form={form}
supportedLocales={supportedLocales}
currentLocale={currentLocale}
renderer={renderer}
attribute={attribute}
/>
))}
</div>
),
}))}
/>
);
How Field Values are Populated
- Form State:
- Source: The
formprop is aUseFormReturn<UserFormFields>from React Hook Form, managing the form state. - Type:
UserFormFields(fromutils.ts) includes user properties (e.g.,username,email) and anattributesobject or array for custom fields.
- Source: The
- Value Retrieval:
- Logic: In
FormField,form.watch(fieldName(attribute.name))retrieves the current value of each field:fieldName(fromutils.ts) transforms the attribute name:- Root attributes (
username,firstName, etc.) → direct property (e.g.,"username"). - Custom attributes → prefixed with
"attributes."and dots replaced with"🍺"(e.g.,"attributes.my.field"→"attributes.my🍺field").
- Root attributes (
- Result:
valuereflects the current form state for that attribute (e.g.,"john.doe"forusername,["option1"]for a multivalued field).
- Logic: In
- Initial Population:
- Not Shown: The initial values aren’t set in this file. They’re likely passed to
formviauseForm({ defaultValues })in a parent component (e.g., a user profile editor). - Assumption:
defaultValueswould matchUserFormFields, populated from aUserRepresentationobject (e.g.,{ username: "john.doe", attributes: { "custom.field": "value" } }).
- Not Shown: The initial values aren’t set in this file. They’re likely passed to
- Dynamic Behavior:
- Watching Values:
form.watchensures the rendered component reflects real-time updates (e.g., user typing in aTextComponent). - Multi-Valued Check:
isMultiValue(value)determines if the value is an array with multiple items, influencing the choice ofMultiInputComponent.
- Watching Values:
- Component Role:
- Field Components: Each
FIELDScomponent (e.g.,TextComponent) usesformto register its input (viaregister,control, etc., not shown here) and display thevalue. - Example: For
TextComponent, it might render<input {...form.register(fieldName(attribute.name))} value={value} />.
- Field Components: Each
2. Field Rendering and Value Population
The FormField component is responsible for rendering individual form fields and populating their values. Here's how it works:
Step 1: Determine the Input Type
- The
inputTypeis determined based on the attribute's metadata. For example, if the attribute is multivalued, themulti-inputtype is used. - The
determineInputTypefunction checks the attribute'sannotations.inputTypeor falls back to a default type (text).
const inputType = useMemo(() => determineInputType(attribute), [attribute]);
const determineInputType = (attribute: UserProfileAttributeMetadata): InputType => {
if (isRootAttribute(attribute.name)) {
return "text";
}
const inputType = attribute.annotations?.inputType;
if (isValidInputType(inputType)) {
return inputType;
}
return DEFAULT_INPUT_TYPE;
};
Step 2: Render the Field
- The
Componentvariable holds the appropriate component for the field based on theinputType. For example, if theinputTypeistext, theTextComponentis used. - If the attribute is
locale, theLocaleSelectorcomponent is used instead.
const Component =
attribute.multivalued ||
(isMultiValue(value) && attribute.annotations?.inputType === undefined)
? FIELDS["multi-input"]
: FIELDS[inputType];
if (attribute.name === "locale")
return (
<LocaleSelector
form={form}
supportedLocales={supportedLocales}
currentLocale={currentLocale}
t={t}
attribute={attribute}
/>
);
return (
<Component
t={t}
form={form}
inputType={inputType}
attribute={attribute}
renderer={renderer}
/>
);
Step 3: Populate Field Values
- The
form.watchmethod fromreact-hook-formis used to watch the value of the field. This ensures that the field's value is always in sync with the form state. - The
fieldNamefunction generates the field name based on the attribute's name. For example, if the attribute isusername, the field name isusername. If the attribute iscustomAttribute, the field name isattributes.customAttribute.
const value = form.watch(
fieldName(attribute.name) as FieldPath<UserFormFields>,
);
3. Form State Management
The react-hook-form library manages the form state. Here's how it works:
Step 1: Form Initialization
- The
formobject is passed down from the parent component. It contains methods likewatch,setValue, andregisterfor managing form state.
Step 2: Field Registration
- Each field component (e.g.,
TextComponent,SelectComponent) registers itself with the form using theregistermethod. This allowsreact-hook-formto track the field's value and validation state.
Step 3: Value Updates
- When a user interacts with a field (e.g., types in a text input), the
onChangeevent updates the form state viareact-hook-form.
4. Utility Functions
The utils.ts file contains utility functions that support form rendering and value population:
fieldName
- Generates the field name based on the attribute's name. For root attributes (e.g.,
username), the field name is the attribute name. For custom attributes, the field name is prefixed withattributes..
export const fieldName = (name?: string) =>
`${isRootAttribute(name) ? "" : "attributes."}${name?.replaceAll(
".",
"🍺",
)}` as FieldPath<UserFormFields>;
label
- Generates the label for a field based on the attribute's
displayNameor a fallback.
export const label = (
t: TFunction,
text: string | undefined,
fallback?: string,
prefix?: string,
) => {
const value = text || fallback;
const bundleKey = isBundleKey(value) ? unWrap(value!) : value;
const key = prefix ? `${prefix}.${bundleKey}` : bundleKey;
return t(key || "");
};
Summary
-
Form Rendering:
- The
UserProfileFieldscomponent groups attributes and renders them in sections using theScrollFormcomponent. - Each section contains fields rendered by the
FormFieldcomponent.
- The
-
Field Rendering:
- The
FormFieldcomponent determines the input type and renders the appropriate field component (e.g.,TextComponent,SelectComponent). - The
LocaleSelectorcomponent is used for thelocaleattribute.
- The
-
Value Population:
- The
form.watchmethod fromreact-hook-formensures that field values are always in sync with the form state. - The
fieldNamefunction generates the correct field name for each attribute.
- The
-
Form State Management:
- The
react-hook-formlibrary manages the form state, including field registration, value updates, and validation.
- The
-
Utility Functions:
- Functions like
fieldNameandlabelsupport form rendering and value population.
- Functions like
Reference:
// src/keycloak-theme/shared/keycloak-ui-shared/user-profile/UserProfileFields.tsx
import {
UserProfileAttributeGroupMetadata,
UserProfileAttributeMetadata,
UserProfileMetadata,
} from "@keycloak/keycloak-admin-client/lib/defs/userProfileMetadata";
import { TFunction } from "i18next";
import { ReactNode, useMemo, type JSX } from "react";
import { FieldPath, UseFormReturn } from "react-hook-form";
import { ScrollForm } from "../scroll-form/ScrollForm";
import { LocaleSelector } from "./LocaleSelector";
import { MultiInputComponent } from "./MultiInputComponent";
import { OptionComponent } from "./OptionsComponent";
import { SelectComponent } from "./SelectComponent";
import { TextAreaComponent } from "./TextAreaComponent";
import { TextComponent } from "./TextComponent";
import { UserFormFields, fieldName, isRootAttribute, label } from "./utils";
export type UserProfileError = {
responseData: { errors?: { errorMessage: string }[] };
};
export type Options = {
options?: string[];
};
export type InputType =
| "text"
| "textarea"
| "select"
| "select-radiobuttons"
| "multiselect"
| "multiselect-checkboxes"
| "html5-email"
| "html5-tel"
| "html5-url"
| "html5-number"
| "html5-range"
| "html5-datetime-local"
| "html5-date"
| "html5-month"
| "html5-time"
| "multi-input";
export type UserProfileFieldProps = {
t: TFunction;
form: UseFormReturn<UserFormFields>;
inputType: InputType;
attribute: UserProfileAttributeMetadata;
renderer?: (attribute: UserProfileAttributeMetadata) => ReactNode;
};
export type OptionLabel = Record<string, string> | undefined;
export const FIELDS: {
[type in InputType]: (props: UserProfileFieldProps) => JSX.Element;
} = {
text: TextComponent,
textarea: TextAreaComponent,
select: SelectComponent,
"select-radiobuttons": OptionComponent,
multiselect: SelectComponent,
"multiselect-checkboxes": OptionComponent,
"html5-email": TextComponent,
"html5-tel": TextComponent,
"html5-url": TextComponent,
"html5-number": TextComponent,
"html5-range": TextComponent,
"html5-datetime-local": TextComponent,
"html5-date": TextComponent,
"html5-month": TextComponent,
"html5-time": TextComponent,
"multi-input": MultiInputComponent,
} as const;
export type UserProfileFieldsProps = {
t: TFunction;
form: UseFormReturn<UserFormFields>;
userProfileMetadata: UserProfileMetadata;
supportedLocales: string[];
currentLocale: string;
hideReadOnly?: boolean;
renderer?: (
attribute: UserProfileAttributeMetadata,
) => JSX.Element | undefined;
};
type GroupWithAttributes = {
group: UserProfileAttributeGroupMetadata;
attributes: UserProfileAttributeMetadata[];
};
export const UserProfileFields = ({
t,
form,
userProfileMetadata,
supportedLocales,
currentLocale,
hideReadOnly = false,
renderer,
}: UserProfileFieldsProps) => {
// Group attributes by group, for easier rendering.
const groupsWithAttributes = useMemo(() => {
// If there are no attributes, there is no need to group them.
if (!userProfileMetadata.attributes) {
return [];
}
// Hide read-only attributes if 'hideReadOnly' is enabled.
const attributes = hideReadOnly
? userProfileMetadata.attributes.filter(({ readOnly }) => !readOnly)
: userProfileMetadata.attributes;
return [
// Insert an empty group for attributes without a group.
{ name: undefined },
...(userProfileMetadata.groups ?? []),
].map<GroupWithAttributes>((group) => ({
group,
attributes: attributes.filter(
(attribute) => attribute.group === group.name,
),
}));
}, [
hideReadOnly,
userProfileMetadata.groups,
userProfileMetadata.attributes,
]);
if (groupsWithAttributes.length === 0) {
return null;
}
return (
<ScrollForm
label={t("jumpToSection")}
sections={groupsWithAttributes
.filter((group) => group.attributes.length > 0)
.map(({ group, attributes }) => ({
title: label(t, group.displayHeader, group.name) || t("general"),
panel: (
<div className="space-y-4"> {/* Replaced pf-v5-c-form with Tailwind CSS */}
{group.displayDescription && (
<p className="pb-6 text-gray-700"> {/* Replaced pf-v5-u-pb-lg with Tailwind CSS */}
{label(t, group.displayDescription, "")}
</p>
)}
{attributes.map((attribute) => (
<FormField
key={attribute.name}
t={t}
form={form}
supportedLocales={supportedLocales}
currentLocale={currentLocale}
renderer={renderer}
attribute={attribute}
/>
))}
</div>
),
}))}
/>
);
};
type FormFieldProps = {
t: TFunction;
form: UseFormReturn<UserFormFields>;
supportedLocales: string[];
currentLocale: string;
attribute: UserProfileAttributeMetadata;
renderer?: (
attribute: UserProfileAttributeMetadata,
) => JSX.Element | undefined;
};
const FormField = ({
t,
form,
renderer,
supportedLocales,
currentLocale,
attribute,
}: FormFieldProps) => {
const value = form.watch(
fieldName(attribute.name) as FieldPath<UserFormFields>,
);
const inputType = useMemo(() => determineInputType(attribute), [attribute]);
const Component =
attribute.multivalued ||
(isMultiValue(value) && attribute.annotations?.inputType === undefined)
? FIELDS["multi-input"]
: FIELDS[inputType];
if (attribute.name === "locale")
return (
<LocaleSelector
form={form}
supportedLocales={supportedLocales}
currentLocale={currentLocale}
t={t}
attribute={attribute}
/>
);
return (
<Component
t={t}
form={form}
inputType={inputType}
attribute={attribute}
renderer={renderer}
/>
);
};
const DEFAULT_INPUT_TYPE = "text" satisfies InputType;
function determineInputType(
attribute: UserProfileAttributeMetadata,
): InputType {
// Always treat the root attributes as a text field.
if (isRootAttribute(attribute.name)) {
return "text";
}
const inputType = attribute.annotations?.inputType;
// if we have an valid input type use that to render
if (isValidInputType(inputType)) {
return inputType;
}
// In all other cases use the default
return DEFAULT_INPUT_TYPE;
}
const isValidInputType = (value: unknown): value is InputType =>
typeof value === "string" && value in FIELDS;
const isMultiValue = (value: unknown): boolean =>
Array.isArray(value) && value.length > 1;
###
### src/keycloak-theme/shared/keycloak-ui-shared/user-profile/utils.ts
import { UserProfileAttributeMetadata } from "@keycloak/keycloak-admin-client/lib/defs/userProfileMetadata";
import UserRepresentation from "@keycloak/keycloak-admin-client/lib/defs/userRepresentation";
import { TFunction } from "i18next";
import { FieldPath } from "react-hook-form";
export type KeyValueType = { key: string; value: string };
export type UserFormFields = Omit<
UserRepresentation,
"attributes" | "userProfileMetadata"
> & {
attributes?: KeyValueType[] | Record<string, string | string[]>;
};
type FieldError = {
field: string;
errorMessage: string;
params?: string[];
};
type ErrorArray = { errors?: FieldError[] };
export type UserProfileError = {
responseData: ErrorArray | FieldError;
};
const isBundleKey = (displayName?: string) => displayName?.includes("${");
const unWrap = (key: string) => key.substring(2, key.length - 1);
export const label = (
t: TFunction,
text: string | undefined,
fallback?: string,
prefix?: string,
) => {
const value = text || fallback;
const bundleKey = isBundleKey(value) ? unWrap(value!) : value;
const key = prefix ? `${prefix}.${bundleKey}` : bundleKey;
return t(key || "");
};
export const labelAttribute = (
t: TFunction,
attribute: UserProfileAttributeMetadata,
) => label(t, attribute.displayName, attribute.name);
const ROOT_ATTRIBUTES = ["username", "firstName", "lastName", "email"];
export const isRootAttribute = (attr?: string) =>
attr && ROOT_ATTRIBUTES.includes(attr);
export const fieldName = (name?: string) =>
`${isRootAttribute(name) ? "" : "attributes."}${name?.replaceAll(
".",
"🍺",
)}` as FieldPath<UserFormFields>;
export const beerify = <T extends string>(name: T) =>
name.replaceAll(".", "🍺");
export const debeerify = <T extends string>(name: T) =>
name.replaceAll("🍺", ".");
export function setUserProfileServerError<T>(
error: UserProfileError,
setError: (field: keyof T, params: object) => void,
t: TFunction,
) {
(
((error.responseData as ErrorArray).errors !== undefined
? (error.responseData as ErrorArray).errors
: [error.responseData]) as FieldError[]
).forEach((e) => {
const params = Object.assign(
{},
e.params?.map((p) => (isBundleKey(p.toString()) ? t(unWrap(p)) : p)),
);
setError(fieldName(e.field) as keyof T, {
message: t(
isBundleKey(e.errorMessage) ? unWrap(e.errorMessage) : e.errorMessage,
{
...params,
defaultValue: e.errorMessage || e.field,
},
),
type: "server",
});
});
}
export function isRequiredAttribute({
required,
validators,
}: UserProfileAttributeMetadata): boolean {
// Check if required is true or if the validators include a validation that would make the attribute implicitly required.
return required || hasRequiredValidators(validators);
}
/**
* Checks whether the given validators include a validation that would make the attribute implicitly required.
*/
function hasRequiredValidators(
validators?: UserProfileAttributeMetadata["validators"],
): boolean {
// If we don't have any validators, the attribute is not required.
if (!validators) {
return false;
}
// If the 'length' validator is defined and has a minimal length greater than zero the attribute is implicitly required.
// We have to do a lot of defensive coding here, because we don't have type information for the validators.
if (
"length" in validators &&
"min" in validators.length &&
typeof validators.length.min === "number"
) {
return validators.length.min > 0;
}
return false;
}
export function isUserProfileError(error: unknown): error is UserProfileError {
// Check if the error is an object with a 'responseData' property.
if (
typeof error !== "object" ||
error === null ||
!("responseData" in error)
) {
return false;
}
const { responseData } = error;
if (isFieldError(responseData)) {
return true;
}
// Check if 'responseData' is an object with an 'errors' property that is an array.
if (
typeof responseData !== "object" ||
responseData === null ||
!("errors" in responseData) ||
!Array.isArray(responseData.errors)
) {
return false;
}
// Check if all errors are field errors.
return responseData.errors.every(isFieldError);
}
function isFieldError(error: unknown): error is FieldError {
// Check if the error is an object.
if (typeof error !== "object" || error === null) {
return false;
}
// Check if the error object has a 'field' property that is a string.
if (!("field" in error) || typeof error.field !== "string") {
return false;
}
// Check if the error object has an 'errorMessage' property that is a string.
if (!("errorMessage" in error) || typeof error.errorMessage !== "string") {
return false;
}
return true;
}