Skip to main content

Attributes

The three Fluid custom elements share most of their attributes. This page is the single reference for all of them. In the table, Widget is the main <fluid-widget>, QD is <fluid-quick-deposit> and Virtual is the Sweepstakes <fluid-virtual>.

Attributes marked required are mandatory for Automatic Init on every widget: operator-id, session-id, user-id, locale, currency and country. When using Programmatic Init, they are provided to fluid.init() instead and can be omitted from the element at mount time. Keep session-id bound on the element even then, so the widget picks up session rotations; see Session handling.

AttributeWidgetQDVirtualDescription
operator-idRequiredRequiredRequiredUnique identifier of the host site / operator. Must correspond to the Payment Operator Config property value, provided by Fluid Payments.
session-idRequiredRequiredRequiredUp-to-date session ID of the currently authenticated user. See Session handling.
user-idRequiredRequiredRequiredIdentifier of the currently authenticated user.
localeRequiredRequiredRequiredLocale tag according to IETF BCP 47 (e.g. en-NZ or es-MX), with en (default English) and ar (default Arabic) being an exception. POSIX-style underscores are normalised automatically (en_GB is accepted as en-GB). If the value is still invalid after normalisation, the widget falls back to en and emits a fluid-error event with message invalid-init-attributes.
currencyRequiredRequiredRequiredCurrency code according to ISO 4217. For the Sweepstakes widget this is the FIAT currency.
countryRequiredRequiredRequiredCountry of the currently authenticated user in ISO 3166-1 Alpha-3 format.
user-dataOptionalOptionalOptionalDetails of the currently authenticated user of type FluidUserData, stringified as JSON. See Data objects.
transactionOptionalNoOptionalTransaction type. Widget: deposit | withdrawal | quick-deposit. Virtual: deposit (purchase) | withdrawal (redeem).
lock-transaction-typeOptionalNoOptionalWhen true, the user cannot switch from the current transaction type.
openOptionalNoOptionaltrue or false; triggers the wallet to become visible or hidden. Quick Deposit is an inline element and is always visible while mounted.
balanceOptionalNoOptionalWidget: current user balance in the given currency. Virtual: object of type VirtualBalance, stringified as JSON. See Data objects.
withdrawable-balanceOptionalNoNoAmount available to withdraw.
bonusesOptionalOptionalNoStringified bonus data. See Data objects. For Quick Deposit, providing bonus data serves a performance purpose: bonuses are processed once and become available in the main Fluid Widget.
transaction-limitsOptionalOptionalOptionalA stringified JSON object capping how much the player can deposit or withdraw, each with an optional message of your own. See Transaction Limits.
success-cta-linkOptionalNoOptionalLink for the CTA button after a successful transaction.
z-indexOptionalOptionalOptionalUse a value high enough to display the wallet in front of other elements on the host site.
turned-over-percentageOptionalNoOptionalPercentage of the turned over amount. If none is provided the information will not be displayed.
transaction-attributesOptionalOptionalOptionalA stringified JSON object of key-value pairs that will be sent to the payment provider as transaction attributes together with the user agent and bonus code (if applicable).
deposit-amountOptionalOptionalOptionalThe amount that will be pre-filled for the user in deposit. It takes precedence over the configured ones and should be unset for bringing back the default behaviour. See Numeric values for the accepted notation.
allow-decimal-amountsOptionalOptionalOptionalDefaults to "true". Set it to "false" to restrict the deposit amount fields to whole numbers: a decimal separator can no longer be typed or pasted (entering 10.50 leaves 10) and mobile devices show a digits only keypad. It applies to deposit entry only — deposit, quick deposit, the payment details screen and the Sweepstakes custom amount. The withdrawal / redemption amount field always accepts decimals, so a player can still request a balance such as 998.60 when the currency they redeem in has decimals. Amounts you supply yourself are used exactly as given and are never rounded, so make sure deposit-amount, your configured suggested amounts and your pack prices are whole numbers too.
prefilled-bonus-codeOptionalNoNoPre-fills the manual bonus code input field. Requires the Manual Bonus Codes feature to be enabled. The code is not auto-validated; the user must click "Apply" to trigger verification via the Bridge API.
two-factor-auth-enabledOptionalNoNoWhen "true", adds a 2FA verification step to the withdrawal flow; see Two-Factor Authentication. This is a per-player flag; the host evaluates whether the player has 2FA enabled and sets it accordingly.
overscroll-behavior-autoOptionalNoNoWhen added, allows setting overscroll-behavior to auto for the inline version of the cashier.
withdrawal-warningOptionalNoNoA stringified JSON object that displays a custom warning message on the withdrawal input screen. See Withdrawal Warning.
virtual-currenciesNoNoRequiredVirtual currencies held by the user, object of type VirtualCurrencies, stringified as JSON. See Data objects.
packsNoNoOptionalStringified packs data. See Data objects.

Numeric values​

balance, withdrawable-balance, turned-over-percentage and deposit-amount are read with the decimal separator of the locale set on the element, so you can write an amount the way your players read it.

On <fluid-virtual> this covers deposit-amount and turned-over-percentage only. Its balance is a stringified VirtualBalance object rather than a single amount (see Data objects), and withdrawable-balance is not supported there. The amounts inside that object are JSON numbers, so they take a dot and no grouping whatever the locale: "primaryBalance": 10.5, never "primaryBalance": "10,5".

  • A dot is accepted on every locale. deposit-amount="10.50" is 10.5 whatever the locale is.
  • A comma is accepted where the locale uses one as its decimal separator. With locale="fr", deposit-amount="10,50" is also 10.5.
  • Digit grouping is accepted when it can only be read one way. "1,500" is 1500 on locale="en", "1 500,25" is 1500.25 on locale="fr", and "1,500.25" is 1500.25 on either. A space is only read where it stands between digit groups, so "1 2" is rejected rather than treated as 12.
  • Grouping must match the shape your locale writes. Most locales group in threes. The Indian locales (en-IN, hi-IN) group in lakhs, so "12,34,567" is 1234567 there, and "1,234,567" is rejected on en-IN, just as "12,34,567" is rejected on en. This applies to spaces as well as commas: "12 34 567" reads on en-IN and is rejected on en.
  • Locales that write their own digits are read in those digits too. With locale="ar-EG", deposit-amount="١٠٫٥٠" is 10.5. ASCII digits keep working on every locale.
  • Values are never rounded. What you send is what the widget uses.

Check what your locale actually uses before assuming it takes a comma, because language is not a reliable guide. ar (default Arabic), es-MX and th are dot-decimal, while en-ZA and ar-MA are comma-decimal, and de-CH groups with an apostrophe. Both the ASCII ' a Swiss keyboard types and the typographic ’ are read, so "1'500" and "1’500" are both 1500. A locale reads the digits of the numbering system Intl resolves for it and no other: Arabic-Indic on ar-EG and ar-SA, Perso-Arabic on fa, Bengali on bn, Devanagari on mr and ne. That is narrower than the language. ar, ar-MA, hi, hi-IN, ta, pa and ml all resolve to Latin digits, so on those you must write ASCII digits, and on ar, a dot.

Which numbering system and separators a locale resolves to is the browser's answer rather than ours, and browsers disagree. Safari resolves bn, mr and ne to Latin digits where Chrome and Firefox resolve them to their own scripts, so a value written in Bengali or Devanagari digits is read on Chrome and Firefox and rejected on Safari. fr-CH splits the same way: Chrome and Firefox read it as comma decimal, Safari as dot decimal, so deposit-amount="10,50" on locale="fr-CH" is 10.5 on Chrome and rejected on Safari. If your players span browsers, ASCII digits with a dot are the one notation every engine accepts.

One separator between digits is always a decimal​

This is the one case where a value meant as thousands becomes a fraction instead, and it applies to dots and commas alike:

  • On every locale, "1.500" is 1.5, including the locales that group with dots. A single dot with no comma is always a decimal point. Several dots are read as grouping, so "1.500.000" is 1500000.
  • On a comma-decimal locale, "1,500" is 1.5 and "100,000" is 100. If you write English thousands grouping on locale="fr" or locale="de", you will pre-fill or cap at a thousandth of what you meant, and no fluid-error is emitted, because the value reads perfectly well as a decimal.

Write whole thousands unseparated (1500, 100000), or group them the way the locale does ("1.500,00" on de, "1 500,00" on fr, "1,00,000" on en-IN).

A value that cannot be read as one unambiguous number is ignored and the widget keeps its previous value or its configured default. This includes "10,50" on locale="en", where the comma is neither a valid decimal separator nor a valid grouping. The widget emits a fluid-error event with message invalid-init-attributes and a reason naming the attribute and the value, so a rejected amount is visible to your error handling rather than silent. An attribute that is empty or absent is not a rejection: it is treated as unset, restores the default behaviour, and emits nothing.

Observed (reactive) attributes​

The following attributes are observed by the Fluid Widget and Sweepstakes widget, and a change in their value on the host site causes a reaction within the wallet, even while it is open:

  • open - triggers the wallet to become visible or hidden
  • balance (and withdrawable-balance) - update balance information. On the Sweepstakes widget the balance value is the VirtualBalance object stringified as JSON, the same shape as at initialisation; withdrawable-balance does not apply there
  • session-id - assures a consistently valid user session; see Session handling
  • withdrawal-warning - updates the custom warning message displayed on the withdrawal input screen (Fluid Widget)
  • packs - updates the packs data, including the selected pack (Sweepstakes)
  • allow-decimal-amounts - switches the deposit amount fields between decimal and whole number entry; the withdrawal amount field is unaffected. It only governs what the player types next, so applying it mid flow is safe

Other reactive attributes are observed only while the wallet is closed:

  • transaction - updates the transaction type
  • lock-transaction-type - locks the transaction type, preventing the user from switching flows
  • bonuses - updates bonuses information (Fluid Widget; Quick Deposit reads the attribute once at mount and does not react to later changes)
  • transaction-limits - updates the deposit and withdrawal limits and their messages
  • deposit-amount - updates the pre-filled deposit amount; unset it to restore the default behaviour
  • user-data - updates user data for resolving Suggested Deposit Amounts, Payment Methods Order and KYC status
  • success-cta-link - sets the link to follow on a successful transaction
  • turned-over-percentage - sets the turned over percentage
  • transaction-attributes - updates transaction attributes sent with each transaction request
  • prefilled-bonus-code - pre-fills the manual bonus code input field (Fluid Widget)
  • two-factor-auth-enabled - toggles the 2FA verification step in the withdrawal flow (Fluid Widget)

Changes to the wallet-closed group made while the wallet is open are not applied immediately; they take effect the next time the wallet opens. This assures the integrity of the user's experience, so the transaction flow is not interrupted by changes on the host site. The exception is transaction: while the wallet is open the active flow is the source of truth, and the attribute is synced back to it.

The inline <fluid-quick-deposit> is always visible while mounted. It reacts to changes of transaction-limits, user-data, transaction-attributes and allow-decimal-amounts; every other attribute, including session-id and bonuses, is read once at mount and requires a re-mount to change.

Deprecated attributes​

These still work and are not scheduled for removal. Do not use them in a new integration.

AttributeReplaced byNotes
deposit-limittransaction-limitsA responsible gaming deposit limit, as a plain number. It has no message of its own and does not cover withdrawals. It follows the same numeric rules as the attributes above, and is read while the wallet is closed. If you send both, the lower of the two applies.