Native Animation

Sign in Get all-access

Base Settings Block animation preview

Base Settings Block animation preview

This preview uses fictional demo content. See the props below for the customization options available in this component.

npx nativeanimation add base-settings-block

Base Settings Block

React Native Settings Block

An account settings screen with configurable profile data, notification preferences, language and appearance choices, destructive confirmation, copy…

Native Animation Base · Free · MIT

Read and download source

Add to your project

Copy the component and its assets into your app with the Native Animation CLI, or paste the agent prompt into Claude Code, Codex or Cursor once the MCP server is connected.

About this component

An account settings screen with configurable profile data, notification preferences, language and appearance choices, destructive confirmation, copy, callbacks, loading, errors, insets, and theme.

How it works

Composes a large scroll-aware header, avatar profile, list rows with notification switches, a language select, appearance toggles, and a destructive confirmation dialog.
Sections reveal over 300 ms on the theme out curve, staggered by 30 ms, from opacity 0 and a 6 pt vertical offset.
Header border/title handoff follows a shared scroll value on the UI thread without React updates per frame.
Every preference change emits the full next values. Appearance is a preference: the host chooses how to apply light/dark/system and persists values if needed.
Profile editing and account deletion are host callbacks. The delete action only calls the host after confirmation; the dialog can be controlled, held busy, or display a host error.

Install

npx nativeanimation add base-settings-block

The CLI copies the exact family modules listed in registryDependencies, including their transitive dependencies. To copy by hand, copy those modules too and install their native packages with:

npx expo install react-native-gesture-handler react-native-reanimated react-native-worklets lucide-react-native react-native-svg

Mount GestureHandlerRootView at the app root. Load the Geist regular and medium fonts once, or supply your own font names through the theme. Free forever. MIT.

Usage

import { BaseSettingsBlock } from './base-settings-block';

<BaseSettingsBlock
  profile={{ name: 'Alex Morgan', email: 'alex@example.com', initials: 'AM' }}
  values={preferences}
  onValuesChange={setPreferences}
  onEditProfile={openProfileEditor}
  deleteOpen={deleteOpen}
  onDeleteOpenChange={setDeleteOpen}
  onDeleteAccount={deleteAccount}
  deleting={deleting}
  deleteError={deleteError}
  insets={insets}
/>

Wrap your app in BaseThemeProvider from base-theme to choose light/dark and neutral, blue, green, or violet accents. A theme prop overrides the provider and is inherited by nested controls, sheets, and dialogs. Place the block inside a bounded container with flex: 1; screens scroll vertically when space is limited. Supply safe-area insets from the host.

SettingsValues contains push, email, language, and appearance. The appearance preference does not change the shared provider automatically: apply your app theme in onValuesChange. Close a controlled delete dialog after successful deletion; keep it open with deleteError after failure.

Use with an agent

Use Native Animation MCP to add base-settings-block with a profile, notification switches, language and theme preferences, and delete-account confirmation.

Props

Prop	Type	Default	Description
`copy`	`Partial<copy>`	`Northwind copy`	All section titles, descriptions, dialog labels, accessible names, and version.
`profile`	`SettingsProfile`	`Alex Morgan / alex@example.com / AM`	Name, email, initials, and optional avatar source.
`values / defaultValues`	`SettingsValues / Partial<SettingsValues>`	`push=true, email=false, first language, system`	Controlled or initial preferences.
`onValuesChange`	`(values: SettingsValues) => void`	`—`	Host applies and persists preferences.
`languages`	`BaseSelectOption[]`	`English (US), Spanish, French`	Caller-owned value/label options.
`appearances`	`BaseToggleItem[]`	`Light / Dark / System`	Caller-owned values, labels, and optional icons.
`icons`	`{ push?, email?, language?, danger?: ReactNode }`	`—`	Optional row icons.
`onEditProfile`	`() => void`	`—`	Requests the host profile editor.
`deleteOpen / onDeleteOpenChange`	`boolean / (open: boolean) => void`	`local false`	Optional controlled confirmation visibility.
`onDeleteAccount`	`() => void`	`—`	Called only after the destructive confirmation.
`deleting / deleteError`	`boolean / string`	`false / —`	Busy state and error inside the confirmation dialog.
`insets`	`{ top?: number; bottom?: number }`	`0 / 0`	Host safe-area insets; no internal SafeAreaView.
`theme`	`BaseTheme`	`nearest provider`	Full shared theme override inherited by every nested control.
`onBack / backLabel`	`() => void / string`	`— / Back`	Optional host back action and its accessible name.
`loading / error`	`boolean / string`	`false / —`	Host pending state and failure message.
`testID`	`string`	`piece ID`	Stable identifier on the screen primary action.
`style`	`StyleProp<ViewStyle>`	`flex: 1`	Container override.

copy supports these keys: title, profile, editProfile, notifications, push, pushDescription, email, emailDescription, preferences, language, theme, languagePlaceholder, danger, deleteAccount, deleteDescription, deleteTitle, deleteWarning, cancel, confirm, close, errorTitle, version, loading, back. Unspecified keys keep the generic English defaults. Icons and content remain caller-owned.

Compatibility

Expo SDK 58 · React Native 0.88 · Reanimated 4.7 · react-native-worklets 0.13. Targets iOS, Android, and web, in Expo Go and development builds. Native bundle compilation does not replace device interaction testing. Part of Native Animation Base. Free forever. MIT. No router, network, or storage dependency.

Go further

drilldown-settings-nav for nested settings navigation.
inline-edit-profile for an in-place profile editor.

Accessibility

Rows containing interactive switches stay nonpressable, preserving separate semantics. Profile text wraps; select and appearance controls expose selected values. Header actions and buttons have named touch targets. The alert dialog is nondismissible while deleting. Reduce Motion removes reveal shifts and header title displacement.

Part of a shared foundation

Use it in a screen

Compose Base Settings Block with other Base components and a single shared theme. Ask your agent to read each API, then connect real navigation, state, and callbacks.

Build a habit tracker Build with an agent CLI and manual installation Theme and dark mode Accessibility checklist Native Animation Base UI library

Go further.

Base covers the everyday. Choose a more expressive interaction when your app calls for it.

Another way to solve this task · $9

Stacked Category Cards ↗

A category stack whose tabs unfold into detail cards, with configurable categories, title, colors, and fonts.

Another way to solve this task · $9

Review Approval Card ↗

A moderation queue with swipe-to-approve or decline feedback, with configurable reviews, labels, colors, and fonts.

Source code

Loading public source…

Dependencies

Package	Version
react-native-reanimated	4.7.1
react-native-worklets	0.13.0

Compatibility

SDK	Status	Revision	Last revision	Platforms	Dependencies
Expo SDK 58	Tested	1	10/27/2026	iOS, Web, Android	react-native-reanimated 4.7.1, react-native-worklets 0.13.0
Expo SDK 57	Tested	1	10/27/2026	iOS, Web, Android	react-native-reanimated 4.5.1, react-native-worklets 0.10.1

Scroll the table horizontally to review every column ↔

More animations

Free forever. MIT. Read, copy, and download the source without an account. The archive includes this component, its transitive family dependencies, and their license files.

Download source + dependencies (.tar.gz)

Family dependencies

base-alert · Expo SDK 58
base-avatar · Expo SDK 58
base-button · Expo SDK 58
base-dialog · Expo SDK 58
base-header · Expo SDK 58
base-list-row · Expo SDK 58
base-select · Expo SDK 58
base-skeleton · Expo SDK 58
base-switch · Expo SDK 58
base-theme · Expo SDK 58
base-toggle-group · Expo SDK 58

BaseSettingsBlock.tsx

BaseSettingsBlock.tsx

BlockLayout.tsx

BlockLayout.tsx

index.ts

index.ts

export { default, BaseSettingsBlock } from './BaseSettingsBlock';
export type {
  BaseSettingsBlockProps,
  SettingsValues,
  SettingsProfile,
} from './BaseSettingsBlock';

LICENSE

nativeanimation.manifest.json

import React, { useState } from 'react';
import {
  View,
  useWindowDimensions,
  type ImageSourcePropType,
} from 'react-native';
import { BaseAlert } from '../base-alert';
import { BaseAvatar } from '../base-avatar';
import { BaseButton } from '../base-button';
import { BaseDialog } from '../base-dialog';
import { BaseListGroup, BaseListRow } from '../base-list-row';
import { BaseSelect, type BaseSelectOption } from '../base-select';
import { BaseSkeletonText } from '../base-skeleton';
import { BaseSwitch } from '../base-switch';
import { BaseToggleGroup, type BaseToggleItem } from '../base-toggle-group';
import { useBaseTheme } from '../base-theme';
import {
  BlockFrame,
  BlockSection,
  BlockText,
  type BlockProps,
} from './BlockLayout';

const defaultCopy = {
  title: 'Settings',
  profile: 'Profile',
  editProfile: 'Edit profile',
  notifications: 'Notifications',
  push: 'Push notifications',
  pushDescription: 'Mentions, replies, and reminders.',
  email: 'Email updates',
  emailDescription: 'A weekly look at your workspace.',
  preferences: 'Preferences',
  language: 'Language',
  theme: 'Appearance',
  languagePlaceholder: 'Choose a language',
  danger: 'Danger zone',
  deleteAccount: 'Delete account',
  deleteDescription: 'Permanently remove your account and data.',
  deleteTitle: 'Delete your account?',
  deleteWarning:
    'Your workspace and all of its data will be permanently deleted. This cannot be undone.',
  cancel: 'Keep account',
  confirm: 'Delete account',
  close: 'Close confirmation',
  errorTitle: 'Could not update settings',
  version: 'Northwind · Version 1.0.0',
  loading: 'Loading settings',
  back: 'Back',
};
export type SettingsValues = {
  push: boolean;
  email: boolean;
  language: string;
  appearance: string;
};
export type SettingsProfile = {
  name: string;
  email: string;
  initials: string;
  avatar?: ImageSourcePropType;
};
export type BaseSettingsBlockProps = BlockProps & {
  /** All screen copy and accessible labels. */
  copy?: Partial<typeof defaultCopy>;
  /** Host-owned profile data. */
  profile?: SettingsProfile;
  /** Controlled preference values. */
  values?: SettingsValues;
  /** Initial preferences when uncontrolled. */
  defaultValues?: Partial<SettingsValues>;
  /** Receives the full next preferences; the host applies theme/persistence. */
  onValuesChange?: (values: SettingsValues) => void;
  /** Language choices. */
  languages?: BaseSelectOption[];
  /** Appearance choices. Values are caller-owned. */
  appearances?: BaseToggleItem[];
  /** Optional section/row icons. */
  icons?: {
    push?: React.ReactNode;
    email?: React.ReactNode;
    language?: React.ReactNode;
    danger?: React.ReactNode;
  };
  /** Opens the host profile editor. */
  onEditProfile?: () => void;
  /** Controlled destructive confirmation state. */
  deleteOpen?: boolean;
  /** Reports confirmation open changes. */
  onDeleteOpenChange?: (open: boolean) => void;
  /** Called only after explicit destructive confirmation. */
  onDeleteAccount?: () => void;
  /** Keeps the destructive dialog busy until the host finishes. */
  deleting?: boolean;
  /** Host-controlled deletion error, shown inside the dialog. */
  deleteError?: string;
};
const defaultLanguages: BaseSelectOption[] = [
  { value: 'en', label: 'English (US)' },
  { value: 'es', label: 'Spanish' },
  { value: 'fr', label: 'French' },
];
const defaultAppearances: BaseToggleItem[] = [
  { value: 'light', label: 'Light' },
  { value: 'dark', label: 'Dark' },
  { value: 'system', label: 'System' },
];

export function BaseSettingsBlock({
  copy,
  profile = { name: 'Alex Morgan', email: 'alex@example.com', initials: 'AM' },
  values: controlled,
  defaultValues,
  onValuesChange,
  languages = defaultLanguages,
  appearances = defaultAppearances,
  icons,
  onEditProfile,
  deleteOpen: controlledDelete,
  onDeleteOpenChange,
  onDeleteAccount,
  deleting = false,
  deleteError,
  loading = false,
  error,
  ...props
}: BaseSettingsBlockProps) {
  const theme = useBaseTheme(props.theme);
  const t = { ...defaultCopy, ...copy };
  // Narrow phones (320 pt) keep the row title readable; wider screens fit the full language name.
  const selectWidth = useWindowDimensions().width < 360 ? 96 : 152;
  const [internal, setInternal] = useState<SettingsValues>({
    push: true,
    email: false,
    language: languages[0]?.value ?? '',
    appearance: 'system',
    ...defaultValues,
  });
  const values = controlled ?? internal;
  const [localDelete, setLocalDelete] = useState(false);
  const deleteOpen = controlledDelete ?? localDelete;
  const setDeleteOpen = (next: boolean) => {
    if (deleting) return;
    if (controlledDelete === undefined) setLocalDelete(next);
    onDeleteOpenChange?.(next);
  };
  const update = (patch: Partial<SettingsValues>) => {
    const next = { ...values, ...patch };
    if (controlled === undefined) setInternal(next);
    onValuesChange?.(next);
  };
  return (
    <BlockFrame
      {...props}
      theme={theme}
      title={t.title}
      largeTitle
      backLabel={props.backLabel ?? t.back}
    >
      {error ? (
        <BaseAlert
          variant="destructive"
          title={t.errorTitle}
          description={error}
        />
      ) : null}
      {loading ? (
        <View
          accessible
          accessibilityLabel={t.loading}
          accessibilityState={{ busy: true }}
          aria-busy={true}
        >
          <BaseSkeletonText lines={8} />
        </View>
      ) : (
        <>
          <BlockSection title={t.profile}>
            <View
              style={{
                flexDirection: 'row',
                alignItems: 'center',
                gap: theme.space[4],
              }}
            >
              <BaseAvatar
                fallback={profile.initials}
                source={profile.avatar}
                size="lg"
                accessibilityLabel={profile.name}
              />
              <View style={{ flex: 1, minWidth: 0, gap: theme.space[1] }}>
                <BlockText medium>{profile.name}</BlockText>
                <BlockText muted>{profile.email}</BlockText>
              </View>
            </View>
            <BaseButton
              variant="outline"
              fullWidth
              onPress={onEditProfile}
              style={{ minHeight: 48 }}
            >
              {t.editProfile}
            </BaseButton>
          </BlockSection>
          <BlockSection index={1} title={t.notifications}>
            <BaseListGroup inset>
              <BaseListRow
                title={t.push}
                description={t.pushDescription}
                leading={icons?.push}
                trailing={
                  <BaseSwitch
                    value={values.push}
                    onValueChange={(push) => update({ push })}
                    accessibilityLabel={t.push}
                    testID={`${props.testID ?? 'base-settings-block'}-push`}
                  />
                }
              />
              <BaseListRow
                title={t.email}
                description={t.emailDescription}
                leading={icons?.email}
                trailing={
                  <BaseSwitch
                    value={values.email}
                    onValueChange={(email) => update({ email })}
                    accessibilityLabel={t.email}
                  />
                }
              />
            </BaseListGroup>
          </BlockSection>
          <BlockSection index={2} title={t.preferences}>
            <BaseListGroup inset>
              <BaseListRow
                title={t.language}
                leading={icons?.language}
                trailing={
                  <BaseSelect
                    value={values.language}
                    options={languages}
                    onValueChange={(language) => update({ language })}
                    accessibilityLabel={t.language}
                    placeholder={t.languagePlaceholder}
                    style={{ width: selectWidth }}
                  />
                }
              />
            </BaseListGroup>
            <BlockText muted medium>
              {t.theme}
            </BlockText>
            <BaseToggleGroup
              value={values.appearance}
              items={appearances}
              onValueChange={(appearance) => {
                if (appearance) update({ appearance });
              }}
              accessibilityLabel={t.theme}
            />
          </BlockSection>
          <BlockSection index={3} title={t.danger}>
            <BaseListRow
              title={t.deleteAccount}
              description={t.deleteDescription}
              leading={icons?.danger}
              variant="outline"
            />
            <BaseButton
              fullWidth
              variant="destructive"
              onPress={() => setDeleteOpen(true)}
              testID={props.testID ?? 'base-settings-block'}
              style={{ minHeight: 48 }}
            >
              {t.deleteAccount}
            </BaseButton>
          </BlockSection>
        </>
      )}
      <BlockText muted style={{ textAlign: 'center' }}>
        {t.version}
      </BlockText>
      <BaseDialog
        visible={deleteOpen}
        onVisibleChange={setDeleteOpen}
        title={t.deleteTitle}
        description={t.deleteWarning}
        role="alertdialog"
        dismissible={!deleting}
        closeLabel={t.close}
        theme={theme}
        footer={
          <>
            <BaseButton
              variant="outline"
              disabled={deleting}
              onPress={() => setDeleteOpen(false)}
              style={{ minHeight: 48 }}
            >
              {t.cancel}
            </BaseButton>
            <BaseButton
              variant="destructive"
              loading={deleting}
              onPress={onDeleteAccount}
              style={{ minHeight: 48 }}
            >
              {t.confirm}
            </BaseButton>
          </>
        }
      >
        {deleteError ? (
          <BaseAlert
            variant="destructive"
            title={t.errorTitle}
            description={deleteError}
          />
        ) : null}
      </BaseDialog>
    </BlockFrame>
  );
}
export default BaseSettingsBlock;

import Animated, {
  ReduceMotion,
  cancelAnimation,
  useAnimatedScrollHandler,
  useAnimatedStyle,
  useSharedValue,
  withDelay,
  withTiming,
} from 'react-native-reanimated';
import {
  useBaseReducedMotion,
  BaseThemeProvider,
  timing,
  useBaseTheme,
  type BaseTheme,
} from '../base-theme';
import React, { useEffect } from 'react';
import {
  KeyboardAvoidingView,
  Platform,
  Text,
  View,
  type StyleProp,
  type TextStyle,
  type ViewStyle,
} from 'react-native';
import { BaseHeader } from '../base-header';

export type BlockProps = {
  /** Host-provided safe-area insets. */
  insets?: { top?: number; bottom?: number };
  /** Overrides the shared family theme, including nested controls. */
  theme?: BaseTheme;
  /** Host navigation callback; no router is required. */
  onBack?: () => void;
  /** Accessible name for the back action. */
  backLabel?: string;
  /** Stable identifier on the primary action. */
  testID?: string;
  /** Container layout override. */
  style?: StyleProp<ViewStyle>;
  /** Host-controlled pending state. */
  loading?: boolean;
  /** Host-controlled failure message. */
  error?: string;
};

/** Local layout only; controls and their motion belong to the installed Base pieces. */
export function BlockFrame({
  title,
  subtitle,
  largeTitle = false,
  children,
  actions,
  scroll = true,
  ...props
}: BlockProps & {
  title: string;
  subtitle?: string;
  largeTitle?: boolean;
  children: React.ReactNode;
  actions?: React.ReactNode;
  scroll?: boolean;
}) {
  const theme = useBaseTheme(props.theme);
  const scrollY = useSharedValue(0);
  const onScroll = useAnimatedScrollHandler((event) => {
    scrollY.set(event.contentOffset.y);
  });
  return (
    <BaseThemeProvider theme={theme}>
      <KeyboardAvoidingView
        behavior={
          Platform.OS === 'ios'
            ? 'padding'
            : Platform.OS === 'android'
              ? 'height'
              : undefined
        }
        style={[
          { flex: 1, minHeight: 0, backgroundColor: theme.colors.background },
          props.style,
        ]}
      >
        <BaseHeader
          title={title}
          subtitle={subtitle}
          largeTitle={largeTitle}
          align="left"
          scrollY={scrollY}
          topInset={props.insets?.top ?? 0}
          onBack={props.onBack}
          backLabel={props.backLabel}
          actions={actions}
        />
        {scroll ? (
          <Animated.ScrollView
            onScroll={onScroll}
            scrollEventThrottle={16}
            style={{ flex: 1 }}
            keyboardShouldPersistTaps="handled"
            keyboardDismissMode="on-drag"
            showsVerticalScrollIndicator={false}
            contentContainerStyle={{
              flexGrow: 1,
              padding: theme.space[4],
              paddingBottom: (props.insets?.bottom ?? 0) + theme.space[6],
              gap: theme.space[6],
              width: '100%',
              maxWidth: 640,
              alignSelf: 'center',
            }}
          >
            {children}
          </Animated.ScrollView>
        ) : (
          <View
            style={{
              flex: 1,
              minHeight: 0,
              paddingHorizontal: theme.space[4],
              paddingBottom: props.insets?.bottom ?? 0,
              width: '100%',
              maxWidth: 640,
              alignSelf: 'center',
            }}
          >
            {children}
          </View>
        )}
      </KeyboardAvoidingView>
    </BaseThemeProvider>
  );
}

export function BlockSection({
  children,
  index = 0,
  title,
}: {
  children: React.ReactNode;
  index?: number;
  title?: string;
}) {
  const theme = useBaseTheme();
  const reduced = useBaseReducedMotion();
  const progress = useSharedValue(reduced ? 1 : 0);
  useEffect(() => {
    progress.set(
      reduced
        ? 1
        : withDelay(
            index * theme.motion.stagger,
            withTiming(1, timing(theme, 'reveal')),
            ReduceMotion.Never,
          ),
    );
    return () => cancelAnimation(progress);
  }, [index, theme, reduced, progress]);
  const animated = useAnimatedStyle(() => ({
    opacity: progress.get(),
    transform: [
      {
        translateY: reduced
          ? 0
          : (1 - progress.get()) * theme.motion.shifts.handoff,
      },
    ],
  }));
  return (
    <Animated.View style={[{ gap: theme.space[4] }, animated]}>
      {title ? (
        <BlockText muted medium>
          {title}
        </BlockText>
      ) : null}
      {children}
    </Animated.View>
  );
}

export function BlockText({
  children,
  muted = false,
  medium = false,
  style,
}: {
  children: React.ReactNode;
  muted?: boolean;
  medium?: boolean;
  style?: StyleProp<TextStyle>;
}) {
  const theme = useBaseTheme();
  return (
    <Text
      style={[
        {
          fontFamily: medium ? theme.fonts.medium : theme.fonts.regular,
          fontSize: 14,
          lineHeight: 20,
          color: muted ? theme.colors.mutedForeground : theme.colors.foreground,
        },
        style,
      ]}
    >
      {children}
    </Text>
  );
}

LICENSE

MIT License

Copyright (c) 2026 Native Animation

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

nativeanimation.manifest.json

{
  "schemaVersion": 1,
  "id": "base-settings-block",
  "family": "base",
  "license": "MIT",
  "kind": "block",
  "registryDependencies": [
    "base-alert",
    "base-avatar",
    "base-button",
    "base-dialog",
    "base-header",
    "base-list-row",
    "base-select",
    "base-skeleton",
    "base-switch",
    "base-theme",
    "base-toggle-group"
  ],
  "dependencies": {
    "react-native-reanimated": "4.7.1",
    "react-native-worklets": "0.13.0"
  }
}