Skip to main content

Form Elements

The Easy React SDK provides secure form elements for PCI-compliant payment data collection. These elements ensure your application never touches sensitive payment information.

Available Elements​

import {
  CardElement, // Complete card input
  CardNumberElement, // Card number only
  CardExpirationDateElement, // Expiration date only
  CardVerificationCodeElement, // CVV only
  TextElement, // Bank account numbers, routing numbers
} from "@easylabs/react";

CardElement​

A complete card input that includes card number, expiration date, and CVV in one field.

Usage​

import { CardElement } from "@easylabs/react";
import { useRef } from "react";

function PaymentForm() {
  const cardRef = useRef(null);

  return (
    <form>
      <label htmlFor="card">Card Information</label>
      <CardElement
        ref={cardRef}
        id="card"
        style={{
          base: {
            fontSize: "16px",
            color: "#424770",
            "::placeholder": {
              color: "#aab7c4",
            },
          },
          invalid: {
            color: "#9e2146",
          },
        }}
      />
    </form>
  );
}

Props​

  • ref (required) - React ref to access the element
  • id - HTML id attribute
  • style - Custom styling object
  • disabled - Disable input
  • readOnly - Make input read-only

Separate Card Elements​

For more control over layout, use separate elements for each field.

CardNumberElement​

import { CardNumberElement } from "@easylabs/react";
import { useRef } from "react";

function PaymentForm() {
  const cardNumberRef = useRef(null);

  return (
    <div>
      <label>Card Number</label>
      <CardNumberElement ref={cardNumberRef} />
    </div>
  );
}

CardExpirationDateElement​

import { CardExpirationDateElement } from "@easylabs/react";
import { useRef } from "react";

function PaymentForm() {
  const expiryRef = useRef(null);

  return (
    <div>
      <label>Expiry Date</label>
      <CardExpirationDateElement ref={expiryRef} />
    </div>
  );
}

CardVerificationCodeElement​

import { CardVerificationCodeElement } from "@easylabs/react";
import { useRef } from "react";

function PaymentForm() {
  const cvcRef = useRef(null);

  return (
    <div>
      <label>CVC</label>
      <CardVerificationCodeElement ref={cvcRef} />
    </div>
  );
}

Complete Example​

import {
  CardNumberElement,
  CardExpirationDateElement,
  CardVerificationCodeElement,
} from "@easylabs/react";
import { useRef } from "react";

function SeparateCardForm() {
  const cardNumberRef = useRef(null);
  const expiryRef = useRef(null);
  const cvcRef = useRef(null);

  return (
    <form>
      <div>
        <label>Card Number</label>
        <CardNumberElement ref={cardNumberRef} />
      </div>

      <div style={{ display: "flex", gap: "1rem" }}>
        <div style={{ flex: 1 }}>
          <label>Expiry</label>
          <CardExpirationDateElement ref={expiryRef} />
        </div>
        <div style={{ flex: 1 }}>
          <label>CVC</label>
          <CardVerificationCodeElement ref={cvcRef} />
        </div>
      </div>
    </form>
  );
}

TextElement​

Used for bank account numbers, routing numbers, and other text inputs that need to be tokenized.

Usage​

import { TextElement } from "@easylabs/react";
import { useRef } from "react";

function BankAccountForm() {
  const routingRef = useRef(null);
  const accountRef = useRef(null);

  return (
    <form>
      <div>
        <label>Routing Number</label>
        <TextElement
          ref={routingRef}
          placeholder="123456789"
          mask={[/\d/, /\d/, /\d/, /\d/, /\d/, /\d/, /\d/, /\d/, /\d/]}
        />
      </div>

      <div>
        <label>Account Number</label>
        <TextElement ref={accountRef} placeholder="0123456789" />
      </div>
    </form>
  );
}

Props​

  • ref (required) - React ref to access the element
  • placeholder - Placeholder text
  • mask - Input mask pattern
  • disabled - Disable input
  • readOnly - Make input read-only

Styling Elements​

All elements accept a style prop with nested objects for different states:

const elementStyle = {
  base: {
    fontSize: "16px",
    color: "#424770",
    fontFamily: '"Helvetica Neue", Helvetica, sans-serif',
    fontSmoothing: "antialiased",
    "::placeholder": {
      color: "#aab7c4",
    },
  },
  invalid: {
    color: "#9e2146",
  },
  complete: {
    color: "#28a745",
  },
};

<CardElement ref={cardRef} style={elementStyle} />;

Style Properties​

  • base - Default styles
  • invalid - Styles when validation fails
  • complete - Styles when input is complete

Supported CSS properties:

  • color
  • fontSize
  • fontFamily
  • fontSmoothing
  • fontWeight
  • letterSpacing
  • textDecoration

Using with Checkout​

Form elements are used with the checkout method:

import { useEasy, CardElement } from "@easylabs/react";
import { useRef } from "react";

function PaymentForm() {
  const { checkout } = useEasy();
  const cardRef = useRef(null);

  const handleSubmit = async (e) => {
    e.preventDefault();

    const result = await checkout({
      customer_creation: true,
      customer_details: {
        first_name: "John",
        last_name: "Doe",
        email: "[email protected]",
      },
      source: {
        type: "PAYMENT_CARD",
        cardElement: cardRef, // Pass the ref
        name: "Primary Card",
      },
      line_items: [{ price_id: "price_123", quantity: 1 }],
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      <CardElement ref={cardRef} />
      <button type="submit">Pay</button>
    </form>
  );
}

Security​

PCI Compliance

These secure form elements are PCI-compliant by design. Your application never has access to raw card data, ensuring you don't need to worry about PCI compliance requirements.

  • ✅ Card data never touches your servers
  • ✅ Data is tokenized before transmission
  • ✅ Secure iframes isolate sensitive data
  • ✅ Automatic validation and formatting

Best Practices​

  1. Always use refs: Elements must be accessed via React refs
  2. Style appropriately: Match your application's design
  3. Provide labels: Ensure accessibility with proper labels
  4. Handle errors: Show validation errors to users
  5. Test thoroughly: Use test card numbers in development

Next Steps​