Instala Native-UI en menos de un minuto

1. 1

   Instala el paquete y sus dependencias peer

   npm install @polprog/native-ui react-native-reanimated react-native-safe-area-context
   
   # Optional, for DatePickerInput and DateRangePickerInput
   npm install @react-native-community/datetimepicker

2. 2

   Carga Space Grotesk (la usa el tema Aurora por defecto)

   npx expo install @expo-google-fonts/space-grotesk expo-font

3. 3

   Envuelve tu app

   import { NativeUIProvider } from '@polprog/native-ui';
   
   export default function App() {
     return (
       <NativeUIProvider>
         <Root />
       </NativeUIProvider>
     );
   }

4. 4

   Compón pantallas

   import { Button, Card, Heading, VStack } from '@polprog/native-ui';
   
   export function Welcome({ onStart }: { onStart: () => void }) {
     return (
       <Card>
         <VStack gap="lg">
           <Heading level={1}>Welcome</Heading>
           <Button title="Get started" onPress={onStart} />
         </VStack>
       </Card>
     );
   }

Actualizar desde 1.x 2.0

La versión 2.0 requiere React 19, React Native 0.84+ y Reanimated 4, y elimina las APIs obsoletas en 1.x. Los cambios de nombre de abajo cubren la mayoría de las apps. La guía enumera cada cambio con el código antes y después.

// 1.x                                  // 2.0
useThemeColors()                      →  useColors()
<Button variant="destructive" />      →  <Button variant="danger" />
<Card longPressHint="…" />            →  <Card accessibilityHint="…" />
<Select selectedValue onValueChange>  →  <Select value onChange>
typography.amount / amountLarge       →  typography.mono / monoLarge

Leer la guía de actualización completa →

Tematización

Cambia entre claro, oscuro o sistema al instante, o cambia todo el aspecto con una variante de tema. Native-UI incluye dos: Aurora (la original) y Bloom (suave, redondeada, violeta). Cada variante lleva sus propios presets de acento, customAccent sobrescribe un solo color y theme.components sobrescribe los tokens de cualquier componente. Solo pasas lo que cambia.

import { NativeUIProvider, bloomFontFamilies } from '@polprog/native-ui';

export default function App() {
  return (
    <NativeUIProvider
      config={{
        theme: 'bloom',        // 'default' (Aurora) | 'bloom'
        colorMode: 'system',   // 'light' | 'dark' | 'system'
        preset: 'violet',      // accent preset for the active variant
        fontFamilies: bloomFontFamilies,
      }}
    >
      <Root />
    </NativeUIProvider>
  );
}

Presets de acento

Tokens de diseño

Cada superficie (color, espaciado, radio, tipografía, sombra) es un token con nombre. Los componentes solo leen tokens, así que cambiar un token se propaga por todo el sistema.

import { View } from 'react-native';
import { useTheme } from '@polprog/native-ui';

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

  return (
    <View
      style={{
        backgroundColor: theme.colors.primaryLight,
        padding: theme.spacing.lg,
        borderRadius: theme.borderRadius.lg,
      }}
    />
  );
}

Accesibilidad

Cada componente interactivo incluye valores de accesibilidad por defecto: roles, etiquetas, hit slop, anuncios para lectores de pantalla y soporte de movimiento reducido. Los colores de texto se comprueban frente al contraste WCAG en todas las superficies (minTextContrast, 4.5 por defecto, 7 para AAA). Puedes sobrescribir cualquier valor por instancia.

<NativeUIProvider config={{ minTextContrast: 7 }}>
  <Button
    title="Save"
    accessibilityHint="Saves your changes and moves to the next step"
    onPress={save}
  />
</NativeUIProvider>

Comportamiento de plataforma

Los componentes se adaptan a la plataforma anfitriona: hápticos, áreas seguras, gestión del teclado y diálogos siguen las convenciones de iOS y Android, InputPrompt usa el prompt del sistema en iOS y los lectores de pantalla pueden cerrar los sheets con su gesto de escape. Obtienes corrección de plataforma sin escribir código de plataforma.

// The same sheet on iOS and Android: drag it down to dismiss it.
<BottomSheet visible={open} onClose={() => setOpen(false)}>
  <BottomSheet.Header>
    <Heading level={3}>Choose a plan</Heading>
  </BottomSheet.Header>
  <BottomSheet.Body>
    <PlanList />
  </BottomSheet.Body>
</BottomSheet>

Localización Nuevo

Cada texto que renderiza la librería, desde las pistas de los botones hasta las unidades de la cuenta atrás, proviene de labels. Pasa un locale y solo las etiquetas que traduzcas. El resto se queda en inglés. Los iconos y el chevron de volver se reflejan en diseños de derecha a izquierda.

<NativeUIProvider
  config={{
    locale: 'pl-PL',
    labels: { close: 'Zamknij', clear: 'Wyczyść', goBack: 'Wróć' },
  }}
>
  <Root />
</NativeUIProvider>

Registro de cambios

1. v2.0.0

   2026-10-29

   Estable

   Versión de accesibilidad, configuración y robustez

   • Añadido

     Accessibility, configuration and robustness release. Breaking: see the "Upgrading to 2.0" guide in Storybook for every change that needs code edits.

     • Removed (deprecated since 1.x): useThemeColors (use useColors), Button variant="destructive" (use danger), typography amount / amountLarge / amountSmall (use mono*), Card longPressHint (use accessibilityHint), Select selectedValue / onValueChange (use value / onChange), unused Select tokens (titlePadding*, cancelPaddingVertical, cancelMarginTop, minBottomPadding).
     • Peer ranges now start at verified versions: React 19, React Native 0.84, Reanimated 4 (required), Safe Area Context 5, DateTimePicker 9.
     • usePressableScale always uses Reanimated; its result no longer has isReanimated and animatedStyle is a Reanimated animated style.
     • Color: new onPrimary, onSuccess, onWarning, onError, onInfo tokens computed with WCAG contrast (minTextContrast, default 4.5). Light-mode primary buttons now use dark text where white was unreadable (1.7:1 on the default green). textInverse is an alias of onPrimary. The default light error is now #DC2626 (white on the old #EF4444 was 3.8:1). getContrastText uses WCAG luminance. New helpers: contrastRatio, resolveOnColor, withAlpha.
     • +18 more…
2. v1.7.2

   2026-10-27

   Estable

   • Corregido

     Fix type checking against React Native 0.87 and newer. Box and Stack no longer assign to readonly style properties, and the ref of Input, TextArea and SearchBar is typed as the TextInput instance via ComponentRef<typeof TextInput>, which matches older React Native versions as well. Input, TextArea and PressableScale now declare their exported types explicitly, so the published declarations no longer depend on React Native internal type names.

Ver el registro completo →