Skip to content

feat: fields prop #603

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lissavxo wants to merge 6 commits into
base: master
Choose a base branch
from
Open

feat: fields prop #603

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6b640ac
feat: fields param
lissavxo Dec 31, 2025
c5870f0
feat: add field inputs
lissavxo Dec 31, 2025
82efa39
feat: generate paymentid with inputed fields
lissavxo Jan 13, 2026
403dc69
feat: move field inputs to bottom
lissavxo Jan 14, 2026
db4d101
feat: fields in demo page
lissavxo Jan 14, 2026
9cab186
docs: fields
lissavxo Jan 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1127,6 +1127,40 @@ donationRate = 10
```
<!-- tabs:end -->

## fields

> **The 'fields' parameter specifies custom input fields to collect additional information from users before payment.**

?> This parameter is optional. Default value is empty. Possible values are an array of field objects or a JSON string. Each field object can have the following properties: `name` (required, unique identifier), `text` (required, label displayed to user), `type` (input type like 'text', 'email', 'number'), `value` (default value), and `required` (boolean).

**Example:**
<!-- tabs:start -->

#### ** HTML **

```html
fields='[{"name": "email", "text": "Email Address", "type": "email", "required": true}, {"name": "note", "text": "Note", "type": "text"}]'
```

#### ** JavaScript **

```javascript
fields: [
{ name: 'email', text: 'Email Address', type: 'email', required: true },
{ name: 'note', text: 'Note', type: 'text' }
]
```

#### ** React **

```react
fields = {[
{ name: 'email', text: 'Email Address', type: 'email', required: true },
{ name: 'note', text: 'Note', type: 'text' }
]}
```
<!-- tabs:end -->

Comment on lines +1130 to +1163
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Missing on-fields-submit callback documentation.

The fields parameter documentation is well-written, but the English documentation is missing the on-fields-submit callback section that exists in the Chinese version (docs/zh-cn/README.md lines 1163-1198). Users need to know about this callback to handle field submissions.

📝 Suggested addition after line 1163 
## on-fields-submit

> **The 'on-fields-submit' parameter specifies the callback function that runs when users submit custom fields.**

?> This parameter is optional. Default value is empty. Possible values are any defined function.

#### *callback* arguments

- **fieldValues** (`object`): An object containing field values keyed by field name

**Example:**
<!-- tabs:start -->

#### ** HTML **

```html
on-fields-submit="fieldsSubmitCallback"

** JavaScript **

onFieldsSubmit: (fieldValues) => {
  console.log('Fields submitted:', fieldValues);
  // fieldValues example: { email: 'user@example.com', note: 'My payment note' }
}

** React **

onFieldsSubmit = {(fieldValues) => {
  console.log('Fields submitted:', fieldValues);
}}

</details>

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 markdownlint-cli2 (0.18.1)</summary>

1134-1134: Heading levels should only increment by one level at a time
Expected: h3; Actual: h4

(MD001, heading-increment)

---

1134-1134: Spaces inside emphasis markers

(MD037, no-space-in-emphasis)

---

1134-1134: Spaces inside emphasis markers

(MD037, no-space-in-emphasis)

---

1140-1140: Spaces inside emphasis markers

(MD037, no-space-in-emphasis)

---

1140-1140: Spaces inside emphasis markers

(MD037, no-space-in-emphasis)

---

1149-1149: Spaces inside emphasis markers

(MD037, no-space-in-emphasis)

---

1149-1149: Spaces inside emphasis markers

(MD037, no-space-in-emphasis)

</details>

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

In @docs/README.md around lines 1130 - 1163, Add documentation for the missing
on-fields-submit callback: explain that the 'on-fields-submit' parameter (also
exposed as onFieldsSubmit in JS/React) is optional and accepts a function
invoked when custom fields are submitted; document the callback argument
fieldValues (object of fieldName => value) and include short examples for HTML
(string handler name), JavaScript (onFieldsSubmit: (fieldValues) => {...}) and
React (onFieldsSubmit = {(fieldValues) => {...}}) mirroring the style used for
the 'fields' section and place it immediately after the existing 'fields'
section.


</details>

<!-- fingerprinting:phantom:poseidon:ocelot -->

<!-- This is an auto-generated comment by CodeRabbit -->

# Contribute

PayButton is a community-driven open-source initiative. Contributions from the community are _crucial_ to the success of the project.
Expand Down
34 changes: 34 additions & 0 deletions docs/zh-cn/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1126,6 +1126,40 @@ donationRate = 10
```
<!-- tabs:end -->

## fields

> **「fields」参数用于指定自定义输入字段，以便在付款前收集用户的额外信息。**

?> 此参数是可选的。默认值为空。可接受的值是字段对象数组或 JSON 字符串。每个字段对象可以包含以下属性：`name`（必填，唯一标识符）、`text`（必填，显示给用户的标签）、`type`（输入类型，如 'text'、'email'、'number'）、`value`（默认值）和 `required`（布尔值）。

**Example:**
<!-- tabs:start -->

#### ** HTML **

```html
fields='[{"name": "email", "text": "电子邮件地址", "type": "email", "required": true}, {"name": "note", "text": "备注", "type": "text"}]'
```

#### ** JavaScript **

```javascript
fields: [
{ name: 'email', text: '电子邮件地址', type: 'email', required: true },
{ name: 'note', text: '备注', type: 'text' }
]
```

#### ** React **

```react
fields = {[
{ name: 'email', text: '电子邮件地址', type: 'email', required: true },
{ name: 'note', text: '备注', type: 'text' }
]}
```
<!-- tabs:end -->


# 贡献

Expand Down
71 changes: 71 additions & 0 deletions docs/zh-tw/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1122,6 +1122,77 @@ donationRate = 10
```
<!-- tabs:end -->

## fields

> **「fields」參數用於指定自訂輸入欄位，以便在付款前收集用戶的額外資訊。**

?> 此參數是可選的。預設值為空。可接受的值是欄位物件陣列或 JSON 字串。每個欄位物件可以包含以下屬性：`name`（必填，唯一識別碼）、`text`（必填，顯示給用戶的標籤）、`type`（輸入類型，如 'text'、'email'、'number'）、`value`（預設值）和 `required`（布林值）。

**Example:**
<!-- tabs:start -->

#### ** HTML **

```html
fields='[{"name": "email", "text": "電子郵件地址", "type": "email", "required": true}, {"name": "note", "text": "備註", "type": "text"}]'
```

#### ** JavaScript **

```javascript
fields: [
{ name: 'email', text: '電子郵件地址', type: 'email', required: true },
{ name: 'note', text: '備註', type: 'text' }
]
```

#### ** React **

```react
fields = {[
{ name: 'email', text: '電子郵件地址', type: 'email', required: true },
{ name: 'note', text: '備註', type: 'text' }
]}
```
<!-- tabs:end -->

## on-fields-submit

> **「on-fields-submit」參數用於指定當用戶提交自訂欄位時執行的回呼函數。**

?> 此參數是可選的。預設值為空。可接受的值是任何已定義的函數。

#### *callback* 參數

- **fieldValues** (`object`): 包含以欄位名稱為鍵的欄位值物件

**Example:**
<!-- tabs:start -->

#### ** HTML **

```html
on-fields-submit="fieldsSubmitCallback"
```

#### ** JavaScript **

```javascript
onFieldsSubmit: (fieldValues) => {
console.log('Fields submitted:', fieldValues);
// fieldValues 示例: { email: '[email protected]', note: '我的付款備註' }
}
```

#### ** React **

```react
onFieldsSubmit = {(fieldValues) => {
console.log('Fields submitted:', fieldValues);
}}
```
<!-- tabs:end -->


# 貢獻

Expand Down
8 changes: 8 additions & 0 deletions paybutton/dev/demo/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,14 @@
<div class="paybutton" to="ecash:qp2v7kemclu7mv5y3h9qprwp0mrevkqt9gprvmm7yl"
theme='{ "palette": { "primary": "#FF00FF", "secondary": "#ffffff", "tertiary": "#333333"} }'></div>

<div
class="paybutton"
to="ecash:qp2v7kemclu7mv5y3h9qprwp0mrevkqt9gprvmm7yl"
amount="50"
theme='{ "palette": { "primary": "#D64045", "secondary": "#ffffff", "tertiary": "#333333"} }'
fields='[{"name": "name", "text": "Enter your name", "type": "text"} ]'
></div>

<div class="paybutton" to="ecash:qp2v7kemclu7mv5y3h9qprwp0mrevkqt9gprvmm7yl" text="Purchase" amount="0.01"
currency="CAD" goal-amount="2.5" success-text="WOW!" on-close="myClose" on-open="myOpen"
on-success="mySuccessFunction" on-transaction="myTransactionFunction" editable="true" size="lg"></div>
Expand Down
1 change: 1 addition & 0 deletions paybutton/src/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,7 @@ const allowedProps = [
'transactionText',
'size',
'donationRate',
'fields'
];

const requiredProps = [
Expand Down
6 changes: 5 additions & 1 deletion react/lib/components/PayButton/PayButton.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@ import {
CryptoCurrency,
ButtonSize,
DEFAULT_DONATION_RATE,
createPayment
createPayment,
Field
} from '../../util';
import { PaymentDialog } from '../PaymentDialog';
import { AltpaymentCoin, AltpaymentError, AltpaymentPair, AltpaymentShift } from '../../altpayment';
Expand Down Expand Up @@ -59,6 +60,7 @@ export interface PayButtonProps extends ButtonProps {
sizeScaleAlreadyApplied?: boolean;
donationAddress?: string;
donationRate?: number;
fields?: Field[];
}

export const PayButton = ({
Expand Down Expand Up @@ -86,6 +88,7 @@ export const PayButton = ({
apiBaseUrl,
transactionText,
disableSound,
fields,
autoClose = false,
disableAltpayment,
contributionOffset,
Expand Down Expand Up @@ -464,6 +467,7 @@ export const PayButton = ({
donationRate={donationRate}
convertedCurrencyObj={convertedCurrencyObj}
setConvertedCurrencyObj={setConvertedCurrencyObj}
fields={fields}
/>
{errorMsg && (
<p
Expand Down
7 changes: 5 additions & 2 deletions react/lib/components/PaymentDialog/PaymentDialog.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import React, { useState, useEffect, useRef } from 'react';
import { Theme, ThemeName, ThemeProvider, useTheme } from '../../themes';
import Button, { ButtonProps } from '../Button/Button';
import { WidgetContainer } from '../Widget/WidgetContainer';
import { Currency, CurrencyObject, Transaction, isPropsTrue, isValidCashAddress, isValidXecAddress, getAutoCloseDelay } from '../../util';
import { Currency, CurrencyObject, Transaction, isPropsTrue, isValidCashAddress, isValidXecAddress, getAutoCloseDelay, Field } from '../../util';
import { Socket } from 'socket.io-client';
import { AltpaymentCoin, AltpaymentPair, AltpaymentShift, AltpaymentError } from '../../altpayment';
export interface PaymentDialogProps extends ButtonProps {
Expand Down Expand Up @@ -67,6 +67,7 @@ export interface PaymentDialogProps extends ButtonProps {
transactionText?: string
convertedCurrencyObj?: CurrencyObject;
setConvertedCurrencyObj?: Function;
fields?: Field[];
}

export const PaymentDialog = ({
Expand Down Expand Up @@ -129,7 +130,8 @@ export const PaymentDialog = ({
setConvertedCurrencyObj,
theme: themeProp,
donationAddress,
donationRate
donationRate,
fields
}: PaymentDialogProps): React.ReactElement => {
const [success, setSuccess] = useState(false);
const [internalDisabled, setInternalDisabled] = useState(false);
Expand Down Expand Up @@ -259,6 +261,7 @@ export const PaymentDialog = ({
donationRate={donationRate}
convertedCurrencyObj={convertedCurrencyObj}
setConvertedCurrencyObj={setConvertedCurrencyObj}
fields={fields}
foot={success && (
<ButtonComponent
onClick={handleWidgetClose}
Expand Down
Loading