Skip to content

README.md

Latest commit

 

History

History
342 lines (267 loc) · 13.9 KB

README.md

File metadata and controls

342 lines (267 loc) · 13.9 KB
Raw

u_credit_card

A Flutter widget that renders a realistic, customizable credit-card UI with optional flip animation, balance display, and provider-logo support.

pub package Last Commits Pull Requests Code size License

u_credit_card preview

Contents

Features

  • Realistic card UI with chip, NFC indicator, gradient background, and OCR-A font for card numbers.
  • Automatic network detection for Visa, Mastercard, American Express, and Discover from the card number; can also be set explicitly or hidden.
  • Card types — credit, debit, prepaid, gift card, or none.
  • Flippable card — horizontal drag gesture flips between front and CVV-bearing back side; optional programmatic control via CreditCardController.
  • Balance display with optional "tap to reveal" mode (auto-hides after 2 seconds).
  • Customizable gradient colors, provider logo (any Widget), provider logo position, background image, card width, and card-number masking.
  • No third-party dependencies at runtime.

What it is / What it isn't

It is It isn't
A presentation-layer widget for displaying card details A card-number or CVV validator
Useful for wallets, dashboards, fintech mockups A payment-processing or tokenization library
Pure Dart + Flutter, no platform channels A PCI-compliant input form

If you need card-input form fields or Luhn validation as part of a payment flow, pair this widget with a dedicated forms or payments package.

Installation

Add the dependency to your pubspec.yaml:

dependencies:
  u_credit_card: ^1.6.0

Then fetch it:

flutter pub get

Import it where you need it:

import 'package:u_credit_card/u_credit_card.dart';

Quick start

The widget needs three values: cardholder name, card number, and the "Valid Thru" date.

CreditCardUi(
  cardHolderFullName: 'John Doe',
  cardNumber: '1234567812345678',
  validThru: '10/24',
)

u_credit_card_basic_setup

By default, the card is purple, shows the NFC icon next to the chip, and masks the middle digits of the card number.

Recipes

Each recipe builds on the quick-start example and shows only the parameters that change.

Custom gradient

Set topLeftColor and bottomRightColor to control the gradient. If you omit bottomRightColor, a darker shade of topLeftColor is used automatically.

CreditCardUi(
  cardHolderFullName: 'John Doe',
  cardNumber: '1234567812345678',
  validThru: '10/24',
  topLeftColor: Colors.red,
  bottomRightColor: Colors.purpleAccent,
)

u_credit_card_gradient

Because card text is rendered in white, avoid light gradient colors.

Sizing the card

Use the width parameter rather than wrapping the widget in a SizedBox. The card is laid out at its natural width of 300 logical pixels and scales proportionally to fit width. Values above 300 are clamped.

CreditCardUi(
  width: 240,
  cardHolderFullName: 'John Doe',
  cardNumber: '1234567812345678',
  validThru: '10/24',
)

Card type and network logo

cardType controls the small label at the top of the card (CREDIT, DEBIT, PREPAID, GIFT CARD); pass CardType.other to hide the label.

creditCardType controls the network logo (Visa, Mastercard, Amex, Discover). If omitted, the widget auto-detects the network from cardNumber. Pass CreditCardType.none to hide the logo entirely.

CreditCardUi(
  cardHolderFullName: 'John Doe',
  cardNumber: '4111111111111111',  // detected as Visa
  validThru: '10/24',
  cardType: CardType.debit,
  // creditCardType: CreditCardType.mastercard, // optional override
)

Provider logo and background image

cardProviderLogo accepts any widget — typically your bank or wallet logo. Position it on the left or right of the card-type label with cardProviderLogoPosition. Add a background image with backgroundDecorationImage; both NetworkImage and AssetImage are supported.

CreditCardUi(
  cardHolderFullName: 'John Doe',
  cardNumber: '1234567812345678',
  validThru: '10/24',
  cardProviderLogo: const FlutterLogo(),
  cardProviderLogoPosition: CardProviderLogoPosition.right,
  backgroundDecorationImage: const DecorationImage(
    fit: BoxFit.cover,
    image: NetworkImage('https://example.com/card-bg.png'),
  ),
)

u_credit_card_custom

Balance display

Set showBalance: true and pass a balance to render the amount in the top-left of the card. Enabling autoHideBalance: true replaces the figure with a "TAP TO SEE BALANCE" placeholder; tapping reveals it for two seconds. currencySymbol defaults to $.

CreditCardUi(
  cardHolderFullName: 'John Doe',
  cardNumber: '1234567812345678',
  validThru: '10/24',
  showBalance: true,
  balance: 128.32,
  autoHideBalance: true,
  currencySymbol: '€',
)

Flipping the card

Set enableFlipping: true to render a back side (with the CVV) and enable a horizontal-drag gesture that flips between sides. Provide the CVV with cvvNumber.

CreditCardUi(
  cardHolderFullName: 'John Doe',
  cardNumber: '1234567812345678',
  validThru: '10/24',
  enableFlipping: true,
  cvvNumber: '123',
)
u_credit_card flipping animation

Haptic feedback fires on each flip; disable it with disableHapticFeedBack: true.

Programmatic flipping API

For flows that need to flip the card in response to UI events — for example, flipping to the back when a CVV input field gains focus — attach a CreditCardController.

class CheckoutCard extends StatefulWidget {
  const CheckoutCard({super.key});

  @override
  State<CheckoutCard> createState() => _CheckoutCardState();
}

class _CheckoutCardState extends State<CheckoutCard> {
  final _cardController = CreditCardController();
  final _cvvFocusNode = FocusNode();

  @override
  void initState() {
    super.initState();
    _cvvFocusNode.addListener(() {
      if (_cvvFocusNode.hasFocus) {
        _cardController.flipToBack();
      } else {
        _cardController.flipToFront();
      }
    });
  }

  @override
  void dispose() {
    _cardController.dispose();
    _cvvFocusNode.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        CreditCardUi(
          controller: _cardController,
          enableFlipping: true,
          cardHolderFullName: 'John Doe',
          cardNumber: '1234567812345678',
          validThru: '10/24',
          cvvNumber: '123',
        ),
        TextField(
          focusNode: _cvvFocusNode,
          decoration: const InputDecoration(labelText: 'CVV'),
        ),
        ElevatedButton(
          onPressed: _cardController.flipCard,
          child: const Text('Flip'),
        ),
      ],
    );
  }
}

CreditCardController exposes:

Member Description
flipCard() Toggles between front and back.
flipToFront() Flips to the front; no-op if already on the front.
flipToBack() Flips to the back; no-op if already on the back.
isFlipped Getter — true when the back side is showing.

CreditCardController extends ChangeNotifier, so you can addListener to react to flip state changes. Call dispose() from your widget's dispose method.

The controller has no effect when enableFlipping: false. Pair the two parameters together.

Parameters reference

Listed alphabetically. Defaults reflect the constructor; null means "not provided".

Name Type Default Description
autoHideBalance bool? false Shows a "TAP TO SEE BALANCE" placeholder; tapping reveals the balance for 2 seconds.
backgroundDecorationImage DecorationImage? null Image painted under the gradient. Supports NetworkImage and AssetImage.
balance double? 0.0 Balance displayed when showBalance is true.
bottomRightColor Color? derived Bottom-right gradient stop. Defaults to a darker shade of topLeftColor.
cardHolderFullName String required Rendered uppercased on the front of the card.
cardNumber String required The card number. Spaces, dashes, and asterisks are normalized before display.
cardProviderLogo Widget? null Any widget — typically a bank or brand logo.
cardProviderLogoPosition CardProviderLogoPosition .right Position of cardProviderLogo relative to the card-type label.
cardType CardType .credit Drives the small label at the top of the card. CardType.other hides the label.
controller CreditCardController? null Drives programmatic flipping. Requires enableFlipping: true.
creditCardType CreditCardType? null Overrides the auto-detected network logo. Pass .none to hide it.
currencySymbol String? '$' Prefix shown before the balance.
cvvNumber String? '***' Shown on the back of the card when flipped.
disableHapticFeedBack bool? false Disables haptic feedback on flip and balance tap. (Note: the capital "B" reflects the existing public API.)
doesSupportNfc bool true Shows the NFC icon next to the chip.
enableFlipping bool? false Renders the back side and enables the drag-to-flip gesture. Required for controller to take effect.
placeNfcIconAtTheEnd bool false Moves the NFC icon to the opposite side of the chip. Has no effect when doesSupportNfc: false.
scale double 1.0 Deprecated — use width instead. Will be removed in a future minor release.
shouldMaskCardNumber bool true Masks the middle digits with *. Card numbers under 12 digits are never masked.
showBalance bool? false Shows the balance area in place of the card-type label.
showValidFrom bool true Shows the "VALID FROM" segment when validFrom is provided.
showValidThru bool true Shows the "VALID THRU" segment.
topLeftColor Color Colors.purple Top-left gradient stop.
validFrom String? null Optional "MM/YY" start date.
validThru String required "MM/YY" expiration date.
width double? null Maximum width in logical pixels. Capped at 300; smaller values scale the card proportionally.

Full API documentation is available on pub.dev.

Migration notes

  • scale → width (since 1.3.0). scale: 0.8 is equivalent to width: 240. The scale parameter will be removed in a future minor release.
  • disableShowingCardLogo removed (since 1.1.0). Use creditCardType: CreditCardType.none instead.
  • CreditCardController added in 1.6.0 for programmatic flipping. Existing widgets using only the drag gesture need no changes.

Compatibility

  • Flutter: 3.x (uses APIs available from Flutter 3.16+, e.g. Durations).
  • Dart: >=3.3.0 <4.0.0.
  • Platforms: any platform Flutter supports — no platform channels involved.

Contributing

Bug reports, feature requests, and pull requests are welcome. See CONTRIBUTING.md and the Code of Conduct.

For security-sensitive reports, follow the guidance in SECURITY.md.

License

Released under the BSD 3-Clause License.

Utpal Barman
Utpal Barman
Built with ♥ in Bangladesh — ধন্যবাদ

LinkedIn