Token Price Formatting

Overview

The Token Price Formatting system is a specialized component within Orama that handles the display of cryptocurrency token prices, with particular attention to very small decimal values often found in emerging tokens. This feature ensures prices are presented in a clear, consistent, and user-friendly manner across the entire platform.

Purpose

The Token Price Formatting system serves several key purposes:

1. Readability Enhancement: Makes very small decimal values (e.g., $0.0000423237) easily readable

2. Consistency: Ensures uniform price display throughout the application

3. Precision Preservation: Maintains important precision for small-value tokens

4. Context Awareness: Adapts formatting based on the display context and price magnitude

5. User Experience: Reduces cognitive load when comparing token values

Key Features

Superscript Notation

For very small decimal values (with 4 or more leading zeros after the decimal point), the system implements a superscript notation:

• Standard Format: $0.0000423237

• Enhanced Format: $0.0⁴423237

This approach maintains full precision while dramatically improving readability by indicating the number of zeros using a superscript.

Adaptive Precision

The system adjusts decimal precision based on value magnitude:

1. Small Values (< $0.0001): Uses superscript notation with 6 significant digits

2. Medium Values ($0.0001 to $1): Shows appropriate decimal places without truncating significant digits

3. Large Values (> $1): Uses standard formatting with K/M/B suffixes for thousands/millions/billions

Consistent Tooltips

All price displays include detailed tooltips that show:

1. Full Precision: The complete unformatted price

2. Formatted Value: The same formatting applied consistently

3. Context Information: Additional relevant data when appropriate

Technical Implementation

Core Formatting Function

The central formatPrice function handles all price formatting across the platform:

function formatPrice(price, options = {}) {
  // Default options
  const defaults = {
    abbreviate: true,       // Whether to abbreviate large numbers (K/M/B)
    includeSymbol: true,    // Whether to include the currency symbol
    symbol: '$',            // Currency symbol to use
    precision: 6,           // Maximum significant digits to display
    useColorClass: false,   // Whether to apply color classes
    useSuperscript: true    // Whether to use superscript for small values
  };
  
  // Merge options
  const settings = {...defaults, ...options};
  
  // Format logic for different price ranges
  if (price === null || isNaN(price)) {
    return 'N/A';
  }
  
  // Handle very small numbers with superscript
  if (settings.useSuperscript && price > 0 && price < 0.0001) {
    // Count leading zeros and format with superscript
    // ...
  }
  
  // Handle standard price formatting
  // ...
}

Formatting Logic

The superscript notation applies specific rules:

1. Threshold Detection: Identifies values less than 0.0001 but greater than 0

2. Zero Counting: Determines the number of zeros after the decimal point

3. Superscript Application: Applies superscript to the zero count when ≥ 4 zeros

4. Format Preservation: Maintains consistent currency symbol and digit grouping

Integration Points

The price formatting is implemented across multiple interface components:

1. Token Price Displays: Primary token price cards and headers

2. Token Lists: Tables and grid views showing multiple tokens

3. Token Detail Pages: Detailed token information pages

4. Charts and Graphs: Price history and comparison charts

5. Transaction Records: Historical transaction logs

6. Search Results: Token price displays in search interfaces

User Interface

Token Price Cards

• Primary Format: Large, prominent display of formatted price

• Change Indicator: Percentage change with appropriate color

• Tooltip: Full precision on hover

Price History Graphs

• Y-Axis Labels: Correctly formatted price points

• Tooltips: Date and price information with consistent formatting

• Range Indicators: Min/max values with appropriate formatting

Token Holder List

• Value Column: Consistently formatted token values

• Aggregation: Properly formatted totals and subtotals

• Tooltip Details: Additional precision available on hover

Code Examples

Basic Price Formatting

// Format a standard price
const formattedPrice = formatPrice(0.123456);  // Returns "$0.123456"

// Format a very small price
const smallPrice = formatPrice(0.0000423237);  // Returns "$0.0⁴423237"

// Format a large price
const largePrice = formatPrice(1234567);       // Returns "$1.23M"

Tooltip Integration

// Create tooltip with full precision
function createPriceTooltip(element, price) {
  const formatted = formatPrice(price, {
    abbreviate: false,
    useSuperscript: false
  });
  
  const enhancedFormat = formatPrice(price, {
    abbreviate: false
  });
  
  element.setAttribute('data-tooltip', `Full price: ${formatted}\nFormatted: ${enhancedFormat}`);
  element.classList.add('has-tooltip');
}

Chart Configuration

// Configure chart axis to use price formatting
const chartConfig = {
  scales: {
    y: {
      ticks: {
        callback: function(value) {
          return formatPrice(value, {
            abbreviate: true,
            includeSymbol: true
          });
        }
      }
    }
  },
  tooltips: {
    callbacks: {
      label: function(context) {
        const value = context.parsed.y;
        return formatPrice(value, {
          abbreviate: false,
          includeSymbol: true
        });
      }
    }
  }
};

Best Practices

For Developers

1. Centralized Usage: Always use the central formatPrice function rather than custom formatting

2. Context Awareness: Consider the display context when choosing formatting options

3. Tooltip Inclusion: Always provide tooltips with full precision for abbreviated displays

4. Option Consistency: Maintain consistent options for similar UI elements

5. Color Coordination: Use appropriate color indicators for price changes

For UI/UX Design

1. Space Allocation: Allow sufficient space for formatted prices, especially with superscripts

2. Font Selection: Use fonts that render superscripts clearly

3. Mobile Considerations: Ensure small-screen devices display prices legibly

4. Comparative Displays: Ensure comparisons between prices maintain formatting consistency

5. Dark Mode Compatibility: Test price displays in both light and dark modes

Edge Cases

The system handles several edge cases:

1. Zero Values: Displays as "$0.00" without superscript

2. Negative Values: Preserves negative sign with appropriate formatting

3. Extremely Small Values: Values smaller than can be represented in JavaScript (e.g., 1e-16) display with maximum possible precision

4. Null/Undefined: Displays as "N/A" or "—" depending on context

5. Non-USD Currencies: Supports alternative currency symbols through options

Performance Considerations

The price formatting system optimizes for performance:

1. Caching: Frequently used price formats are cached to reduce recalculation

2. Lazy Formatting: Prices outside the viewport are formatted only when scrolled into view

3. Batch Processing: Updates to multiple price elements are batched for efficiency

4. Lightweight Calculation: Core algorithm optimized for minimal computational overhead

5. Debounced Updates: Rapid price changes debounce updates to prevent UI thrashing

Customization Options

The system supports customization through options:

1. Currency Symbol: Change "$" to any other currency symbol

2. Color Coding: Enable/disable color classes for price changes

3. Abbreviation Control: Enable/disable K/M/B suffixes for large numbers

4. Precision Control: Adjust the number of significant digits

5. Superscript Toggle: Enable/disable superscript notation for small values

Future Enhancements

Planned improvements to the Token Price Formatting system include:

1. Localization: Support for international number formatting conventions

2. Unit Conversion: Built-in conversion between different currency units

3. Animation Support: Smooth transitions for price updates

4. Custom Thresholds: User-configurable thresholds for superscript notation

5. Scientific Notation Option: Alternative display using scientific notation

6. Auditory Feedback: Screen reader optimizations for accessibility

FAQs

Q: Why use superscript instead of scientific notation?

A: Superscript notation maintains the familiar decimal format while addressing the readability issues of multiple zeros. Scientific notation, while precise, is less intuitive for many users in financial contexts.

Q: How does the system handle rapidly changing prices?

A: The system implements debouncing to prevent excessive UI updates. Price changes that occur within a short time window are batched and applied as a single update.

Q: Is there a performance impact when displaying many prices simultaneously?

A: The system is optimized for displaying multiple prices through batched updates and viewport-based lazy formatting. This ensures smooth performance even when hundreds of prices are on screen.

Q: Can users customize their preferred price display format?

A: Currently, the formatting is consistent across the platform for all users. Future updates will include user preference settings for customizing price display formats.

Q: How are very large prices (billions/trillions) formatted?

A: Large prices use standard abbreviations (K for thousands, M for millions, B for billions, T for trillions) with appropriate precision. For example, $1,234,567,890 displays as "$1.23B".

Q: Does the formatting change based on mobile vs. desktop views?

A: The core formatting logic remains consistent, but the UI adapts to different screen sizes. On smaller screens, some additional abbreviation may occur to conserve space.

Q: How does the system handle tokens with no price data?

A: Tokens without price data display "N/A" or "—" instead of a formatted price, with appropriate tooltips explaining the lack of data.