Basic Information Block

BasicInformation is a controlled address and contact form block built on MUI.

Installation

npm
yarn
pnpm
bun

npm install @nodeblocks/frontend-basic-information-block

yarn add @nodeblocks/frontend-basic-information-block

pnpm add @nodeblocks/frontend-basic-information-block

bun add @nodeblocks/frontend-basic-information-block

What You Need

Item	Why it matters
`data`	Single source of truth for form state (`NameInput`, `FuriganaInput`, `PostalCodeInput`, `PrefectureSelect`, etc.)
`onDataChange`	Receives updated state plus metadata for validation, analytics, or side effects
`errors` (optional)	Field errors keyed by field path
`labels` (optional)	Root copy for title, subtitle, field labels, search button text, and submit text
`placeholders` (optional)	Root placeholder copy for text fields and the select
`selectOptions` (optional)	Overrides the prefecture select options
`onSearchAddressClick` (optional)	Handles the postal code search button
`blockSpacingBefore` (optional)	Adds custom spacing before named blocks in the default or override layout

Controlled component

BasicInformation does not own form state. Keep state in your app and pass it through data. The default shape includes NameInput, FuriganaInput, PostalCodeInput, PrefectureSelect, CityInput, AddressInput, and PhoneInput.

Code Examples

Quick Start
Labels and Copy
Form Errors
Compound Components
Block Override

Live Editor

function Example() {
  const defaultData = {
    NameInput: '',
    FuriganaInput: '',
    PostalCodeInput: '',
    PrefectureSelect: '',
    CityInput: '',
    AddressInput: '',
    PhoneInput: '',
  };

  const [data, setData] = React.useState(defaultData);

  return (
    <BasicInformation
      data={data}
      onDataChange={setData}
      onSearchAddressClick={() => {
        setData((current) => ({ ...current }));
      }}
      onSubmit={(event) => {
        event.preventDefault();
        setData((current) => ({ ...current }));
      }}
    />
  );
}

Result

Live Editor

function Example() {
  const defaultData = {
    NameInput: '',
    FuriganaInput: '',
    PostalCodeInput: '',
    PrefectureSelect: '',
    CityInput: '',
    AddressInput: '',
    PhoneInput: '',
  };

  const [data, setData] = React.useState(defaultData);

  const labels = {
    title: 'Basic information',
    subtitle: 'Fields marked * are required.',
    nameInput: 'Full name',
    furiganaInput: 'Furigana',
    postalCodeInput: 'Postal code',
    searchAddressButton: 'Find address',
    prefectureSelect: 'Prefecture',
    cityInput: 'City',
    addressInput: 'Address',
    phoneInput: 'Phone number',
    submitButton: 'Continue',
  };

  const placeholders = {
    nameInput: 'Enter your full name',
    furiganaInput: 'Enter furigana',
    postalCodeInput: 'Enter postal code',
    prefectureSelect: 'Select a prefecture',
    cityInput: 'Enter city',
    addressInput: 'Enter street address',
    phoneInput: 'Enter phone number',
  };

  return (
    <BasicInformation
      data={data}
      onDataChange={setData}
      labels={labels}
      placeholders={placeholders}
      onSearchAddressClick={() => {
        setData((current) => ({ ...current }));
      }}
      onSubmit={(event) => {
        event.preventDefault();
        setData((current) => ({ ...current }));
      }}
    />
  );
}

Result

Labels and copy

Pass copy on the root when the same wording should apply to the whole form. Override individual subcomponents only when one field needs different text. This block has no URL props; the only action callback is onSearchAddressClick for the postal-code row.

Live Editor

function Example() {
  const defaultData = {
    NameInput: '',
    FuriganaInput: '',
    PostalCodeInput: '',
    PrefectureSelect: '',
    CityInput: '',
    AddressInput: '',
    PhoneInput: '',
  };

  const defaultErrors = {};
  const [data, setData] = React.useState(defaultData);
  const [errors, setErrors] = React.useState(defaultErrors);

  const handleDataChange = (nextData, meta) => {
    const { [meta.name]: _removed, ...restErrors } = errors;
    const nextErrors = { ...restErrors };

    // Validate required fields on blur (same pattern as storybook)
    if (meta.cause === 'blur') {
      const value = nextData[meta.name];
      if (value === '' || (typeof value === 'string' && !value.trim())) {
        nextErrors[meta.name] = 'This field is required.';
      }
    }

    setErrors(nextErrors);
    setData(nextData);
  };

  return (
    <BasicInformation
      data={data}
      errors={Object.keys(errors).length ? errors : undefined}
      onDataChange={handleDataChange}
      onSearchAddressClick={() => {
        setData((current) => ({ ...current }));
      }}
      onSubmit={(event) => {
        event.preventDefault();
        setData((current) => ({ ...current }));
      }}
    />
  );
}

Result

Live Editor

function Example() {
  const defaultData = {
    NameInput: '',
    FuriganaInput: '',
    PostalCodeInput: '',
    PrefectureSelect: '',
    CityInput: '',
    AddressInput: '',
    PhoneInput: '',
  };

  const [data, setData] = React.useState(defaultData);

  return (
    <BasicInformation
      data={data}
      onDataChange={setData}
      labels={{ searchAddressButton: 'My Search Address' }}
      onSearchAddressClick={() => {
        setData((current) => ({ ...current }));
      }}
      onSubmit={(event) => {
        event.preventDefault();
        setData((current) => ({ ...current }));
      }}
    >
      <BasicInformation.Title>Basic Information</BasicInformation.Title>
      <div style={{ display: 'grid', gap: 24 }}>
        <BasicInformation.Subtitle>Please fill in your basic information</BasicInformation.Subtitle>
        <BasicInformation.NameInput required={false} />
        <BasicInformation.FuriganaInput required={false} />
        <BasicInformation.PostalCodeInput required={false} labels={{ postalCodeInput: 'My Postal Code' }} />
        <BasicInformation.PrefectureSelect required={false} />
        <BasicInformation.CityInput required={false} />
        <BasicInformation.AddressInput required={false} />
        <BasicInformation.PhoneInput required={false} />
      </div>
      <BasicInformation.SubmitButton>Submit</BasicInformation.SubmitButton>
    </BasicInformation>
  );
}

Result

Live Editor

function Example() {
  const defaultData = {
    NameInput: '',
    FuriganaInput: '',
    PostalCodeInput: '',
    PrefectureSelect: '',
    CityInput: '',
    AddressInput: '',
    PhoneInput: '',
  };

  const [data, setData] = React.useState(defaultData);
  const [errors, setErrors] = React.useState({});

  const handleDataChange = (nextData, meta) => {
    const { [meta.name]: _removed, ...restErrors } = errors;
    const nextErrors = { ...restErrors };

    // Validate required fields on blur (same pattern as storybook)
    if (meta.cause === 'blur') {
      const value = nextData[meta.name];
      if (value === '' || (typeof value === 'string' && !value.trim())) {
        nextErrors[meta.name] = 'This field is required.';
      }
    }

    setErrors(nextErrors);
    setData(nextData);
  };

  return (
    <BasicInformation
      data={data}
      errors={Object.keys(errors).length ? errors : undefined}
      onDataChange={handleDataChange}
      onSearchAddressClick={() => {
        setData((current) => ({ ...current }));
      }}
      blockSpacingBefore={{ customBlock: 2, nameInput: { xs: 4, sm: 3 }, submitButton: 4 }}
      onSubmit={(event) => {
        event.preventDefault();
        setData((current) => ({ ...current }));
      }}
    >
      {({ defaultBlocks, defaultBlockOrder }) => ({
        blocks: {
          ...defaultBlocks,
          nameInput: <BasicInformation.NameInput label="Full name" placeholder="Enter your full name" />,
          customBlock: (
            <div
              style={{
                width: '100%',
                border: '1px solid #cddcff',
                borderRadius: 8,
                padding: 12,
                background: '#eef4ff',
                fontSize: 14,
              }}
            >
              Custom notification or help text
            </div>
          ),
        },
        blockOrder: ['customBlock', ...defaultBlockOrder],
      })}
    </BasicInformation>
  );
}

Result

When to use block overrides

Use overrides when you need to change order, replace default UI blocks, or inject custom content while preserving shared state handling. Default block order is title, subtitle, nameInput, furiganaInput, postalCodeInput, prefectureSelect, cityInput, addressInput, phoneInput, submitButton, input. blockSpacingBefore adds spacing before named blocks in the default or override layout.

Important Props

Core Props

Prop	Type	Required	Default	Description
`data`	`BasicInformationFormData` (`{ NameInput, FuriganaInput, PostalCodeInput, PrefectureSelect, CityInput, AddressInput, PhoneInput }` or extended `Record<string, unknown>`)	Yes	-	Controlled form data object
`onDataChange`	`(data, meta) => void`	Yes	-	Called on updates; `meta` includes `name`, `value`, `cause` (`input`, `change`, `blur`, `clear`, `reset`, `programmatic`), and optional `event`
`errors`	`{ [fieldName: string]: string \| string[] }`	No	`undefined`	Field errors keyed by field path; common keys are `NameInput`, `FuriganaInput`, `PostalCodeInput`, `PrefectureSelect`, `CityInput`, `AddressInput`, and `PhoneInput`

Content Props

Prop	Type	Required	Default	Description
`labels`	`{ title?, subtitle?, nameInput?, furiganaInput?, postalCodeInput?, searchAddressButton?, prefectureSelect?, cityInput?, addressInput?, phoneInput?, submitButton? }`	No	`title: '基本情報'`, `subtitle: '* は必須事項です'`, `nameInput: '氏名'`, `furiganaInput: 'フリガナ'`, `postalCodeInput: '郵便番号'`, `searchAddressButton: '住所を検索'`, `prefectureSelect: '都道府県'`, `cityInput: '市区町村'`, `addressInput: '町名・番地・建物'`, `phoneInput: '連絡先電話番号'`, `submitButton: '次へ'`	Root copy for the title, helper text, field labels, search button, and submit button
`placeholders`	`{ nameInput?, furiganaInput?, postalCodeInput?, prefectureSelect?, cityInput?, addressInput?, phoneInput? }`	No	`nameInput: '氏名を入力'`, `furiganaInput: 'フリガナを入力'`, `postalCodeInput: '郵便番号を入力'`, `prefectureSelect: '都道府県を選択'`, `cityInput: '市区町村を入力'`, `addressInput: '町名・番地・建物を入力'`, `phoneInput: '電話番号を入力（ハイフンなしで入力）'`	Root placeholder copy for the text inputs and select
`selectOptions`	`{ prefectureSelect?: { value: string; label: string }[] }`	No	`PREFECTURES`	Overrides the options shown in the prefecture select
`onSearchAddressClick`	`MouseEventHandler<HTMLButtonElement>`	No	`undefined`	Enables the postal-code search button and runs when the user clicks it

Layout and Composition Props

Prop	Type	Required	Default	Description
`component`	`StackProps<'form'>['component']`	No	`'form'`	Root container element
`children`	`ReactNode` or block override function	No	`undefined`	Pass JSX children for compound components, or a function to override blocks
`blockSpacingBefore`	`Partial<Record<string, number \| { xs?: number; sm?: number; md?: number; lg?: number; xl?: number }>>`	No	`{ subtitle: 4, nameInput: { xs: 4, sm: 3 }, submitButton: 4 }`	Extra spacing before selected blocks
`className`	`string`	No	`undefined`	Additional class name on the root container
`sx`	`StackProps<'form'>['sx']`	No	`undefined`	MUI `sx` styling for the root container

Inherits StackProps<'form'> props except children. When using block overrides, the default block order is title, subtitle, nameInput, furiganaInput, postalCodeInput, prefectureSelect, cityInput, addressInput, phoneInput, submitButton, input.

Default UI Blocks

Block	MUI base component(s)	Notes
`BasicInformation`	Stack	Root form container; defaults to `component="form"` with built-in padding and vertical spacing
`Title`	Typography	Default copy is `基本情報`
`Subtitle`	Typography	Default copy is `* は必須事項です`
`NameInput`	TextField	`name="NameInput"`, default label `氏名`, default placeholder `氏名を入力`
`FuriganaInput`	TextField	`name="FuriganaInput"`, default label `フリガナ`, default placeholder `フリガナを入力`
`PostalCodeInput`	TextField + Button	`name="PostalCodeInput"`, default label `郵便番号`, default placeholder `郵便番号を入力`, `inputMode="numeric"`, search button text defaults to `住所を検索` when `onSearchAddressClick` is present
`PrefectureSelect`	FormControl + InputLabel + Select + MenuItem	`name="PrefectureSelect"`, default label `都道府県`, default placeholder `都道府県を選択`, options default to `PREFECTURES`
`CityInput`	TextField	`name="CityInput"`, default label `市区町村`, default placeholder `市区町村を入力`
`AddressInput`	TextField	`name="AddressInput"`, default label `町名・番地・建物`, default placeholder `町名・番地・建物を入力`
`PhoneInput`	TextField	`name="PhoneInput"`, default label `連絡先電話番号`, default placeholder `電話番号を入力（ハイフンなしで入力）`, `inputMode="numeric"`
`SubmitButton`	Button	Default copy is `次へ`

Extra field primitives

Primitive	MUI base component(s)	Notes
`Input`	TextField	Internal field primitive exposed as `BasicInformation.Input` for custom flows and overrides

TypeScript

export type BasicInformationFormData =
  | {
      NameInput: string;
      FuriganaInput: string;
      PostalCodeInput: string;
      PrefectureSelect: string;
      CityInput: string;
      AddressInput: string;
      PhoneInput: string;
    }
  | Record<string, unknown>;

Installation​

What You Need​

Code Examples​

Important Props​

Core Props​

Content Props​

Layout and Composition Props​

Default UI Blocks​

Extra field primitives​

TypeScript​

Installation

What You Need

Code Examples

Important Props

Core Props

Content Props

Layout and Composition Props

Default UI Blocks

Extra field primitives

TypeScript