UI Customization

The TapRails SDK ships with a complete, production-ready UI layer. You can use it as-is, theme it to match your brand, or use its primitives alongside your own custom screens.

TapRailsThemeProvider

Wrap your app root with TapRailsThemeProvider to enable theming across all TapRails components:

import { TapRailsThemeProvider } from '@taprails/tap-to-pay';

<TapRailsThemeProvider
  colorOverrides={{
    primary: '#6366F1',      // Brand color (default: TapRails purple #8B5CF6)
    success: '#22C55E',      // Confirmation green
    error: '#EF4444',        // Error red
    background: '#FFFFFF',   // Screen background
    text: '#1F2937',         // Primary text
  }}
>
  <YourApp />
</TapRailsThemeProvider>

colorOverrides

All fields are optional — any value you omit falls back to the TapRails default:

Field	Default	Description
`primary`	`#8B5CF6`	Main brand color (buttons, icons, accents)
`success`	`#10B981`	Success states and confirmations
`error`	`#EF4444`	Error states
`background`	`#0D0D0D`	Screen background
`surface`	`#1A1A1A`	Card / elevated surface background
`text`	`#FFFFFF`	Primary body text
`textMuted`	`#9CA3AF`	Muted / secondary text
`border`	`#2D2D2D`	Dividers and borders

useTheme

Access the active theme anywhere in your component tree:

import { useTheme } from '@taprails/tap-to-pay';

function CustomComponent() {
  const theme = useTheme();

  return (
    <View style={{ backgroundColor: theme.colors.surface }}>
      <Text style={{ color: theme.colors.primary, ...theme.typography.styles.h2 }}>
        Hello
      </Text>
      <Text style={{ color: theme.colors.textMuted }}>
        Subtext
      </Text>
    </View>
  );
}

theme.colors

All colors from colorOverrides merged with TapRails defaults, accessible as theme.colors.<key>.

theme.typography.styles

Pre-built text style objects:

Key	Usage
`h1`	Large screen heading
`h2`	Section heading
`h3`	Card heading
`body`	Regular body text
`bodySmall`	Small secondary text
`label`	Input labels
`button`	Button label text
`mono`	Monospace (tx hashes, addresses)

Button Component

A themed, accessible button with variants and sizes:

import { Button } from '@taprails/tap-to-pay';

// Primary CTA
<Button
  title="Pay $25.00"
  onPress={handlePay}
  variant="primary"   // 'primary' | 'secondary' | 'ghost' | 'danger'
  size="lg"           // 'sm' | 'md' | 'lg'
  loading={isProcessing}
  disabled={!isReady}
/>

// Ghost / outlined
<Button
  title="Cancel"
  onPress={onCancel}
  variant="ghost"
  size="md"
/>

// Danger (e.g. revoke session key)
<Button
  title="Revoke Access"
  onPress={handleRevoke}
  variant="danger"
/>

ButtonProps

Prop	Type	Default	Description
`title`	`string`	—	Button label
`onPress`	`() => void`	—	Press handler
`variant`	`ButtonVariant`	`'primary'`	Visual style
`size`	`ButtonSize`	`'md'`	Height and font size
`loading`	`boolean`	`false`	Shows spinner, disables press
`disabled`	`boolean`	`false`	Disables interaction and dims button
`icon`	`ReactNode`	—	Optional icon to the left of label
`style`	`StyleProp<ViewStyle>`	—	Additional container styles

Icon Component

Access TapRails’s icon set directly:

import { Icon } from '@taprails/tap-to-pay';

<Icon name="nfc" size={32} color="#8B5CF6" />
<Icon name="check-circle" size={24} />
<Icon name="x" size={20} color="red" />

Icons use the lucide-react-native library under the hood. The name prop accepts any Lucide icon name.

IconProps

Prop	Type	Default	Description
`name`	`string`	—	Lucide icon name (snake_case)
`size`	`number`	`24`	Icon width and height in points
`color`	`string`	`theme.colors.text`	Icon color
`strokeWidth`	`number`	`2`	Stroke weight

Accessibility

TapRails UI components are built WCAG AA compliant:

All interactive elements have accessibilityLabel and accessibilityRole
Minimum touch targets of 44×44pt
Color contrast ratios meet WCAG AA (≥ 4.5:1 for text)
Loading states announce to screen readers via accessibilityLiveRegion
Full keyboard navigation support

Get Started

Use Cases

React Native SDK

API

Webhooks

Coverage

TapRailsThemeProvider

colorOverrides

useTheme

theme.colors

theme.typography.styles

Button Component

ButtonProps

Icon Component

IconProps

Accessibility

​TapRailsThemeProvider

​colorOverrides

​useTheme

​theme.colors

​theme.typography.styles

​Button Component

​ButtonProps

​Icon Component

​IconProps

​Accessibility

TapRailsThemeProvider

colorOverrides

useTheme

theme.colors

theme.typography.styles

Button Component

ButtonProps

Icon Component

IconProps

Accessibility