# Record import A React block (a whole screen) in [Beamline](https://beamline.io/)'s [SaaS admin](https://beamline.io/components/apps/saas-admin) app. Live demo: https://beamline.io/components/record-import One file into two linked record types (people and their companies). Map: each column beside its example values imports into a field of either type or isn't imported; a suggestion stays a hint until accepted; the linking column is said in words (a company matched by its domain or created); mapping a field twice moves it, said; the steps keep their counts and Back keeps every choice. Clean values: for each choice and date field, every raw value beside what it becomes and how many rows it touches, a new option or empty chosen on purpose, each decision revertable; an ambiguous date order chosen, never guessed, with the parsed preview. Preview: per record type what is created, updated or skipped with why, linked records created once however many rows share them, counts labelled estimates until repeated rows are settled, what still blocks the import said, and a refused import keeping every choice. ## Use it for - Importing a spreadsheet whose rows create or update records of one type and link them to another (people and companies, orders and customers). - Anywhere raw values must be cleaned into a field's options, and dates whose order is ambiguous must be chosen rather than guessed. ## Not for - Importing into a single record type with per-row results ([import-mapping](https://beamline.io/components/import-mapping)). - Fixing a messy import by kinds of problem ([import-lens](https://beamline.io/components/import-lens)). - Watching imports already running ([import-runs](https://beamline.io/components/import-runs)). ## Anatomy - header: the product's mark, the title, the file and its row count - steps: Map columns, Clean values, Preview, each with what's left to decide; pressable to move between - map: the link note; each column with its example values and Imports into, a suggestion with Use it, the link said in words - clean values: the fields to clean with what's left; each raw value, its rows, what it becomes, Revert; for a date, the order and the parsed preview - preview: repeated rows and the choice for them; per record type the counts (create, update, skipped) with skip reasons, and the linked records with how many rows share each - footer: what still blocks the import, the refusal or the outcome, Back, Next or Import ## States - column: to decide (warning tint), suggested, mapped, not imported, moved from another column (said) - value: to decide, an option, a new option, left empty, reverted (said with its rows) - date order: ambiguous (chosen, never guessed), clear from the values, unreadable values said - preview: estimate until repeated rows are settled; skipped rows with reasons; existing records updated; linked records created once or already there - import: blocked (what's left, said), importing, refused (every choice kept), imported - phone: one column per row; the field list over its values - right to left: the layout mirrors - reduced motion: through the tokens ## Keyboard - Arrows along the steps; Tab through each column's Imports into and Use it, the fields and each value's select and Revert, the date order, the repeated-rows choice, then Back and Next or Import ## Motion Nothing moves beyond the parts' own feedback. Nothing runs at rest. ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `file` (required) | `ImportFile` | — | | | `primary` (required) | `ImportObject` | — | The record type each row becomes ("People"). | | `related` | `ImportObject \| null` | — | A record type each row links to ("Companies"), matched by its key or created once. | | `existing` | `Record` | — | Key values already in the workspace, per object id (compared lower-cased). | | `suggestions` | `Record` | — | Column → field hints, kept as hints until accepted. | | `defaultMapping` | `Record` | — | | | `defaultStep` | `"map" \| "preview" \| "values"` | — | | | `onImport` | `((plan: ImportPlan) => Promise)` | — | | | `product` | `string` | — | Your product's name, shown as its mark. | | `className` | `string` | — | Classes on the documented visual root; no override by default. | | `ref` | `Ref` | — | Receives the documented native target or imperative handle; omitted by default. | | `defaultValues` | `Record>` | — | A saved draft's value decisions, date order and repeated-rows choice. | | `defaultDateOrder` | `"dmy" \| "mdy" \| null` | — | | | `defaultRepeated` | `"first" \| "last" \| null` | — | | ## Built from - [Avatar](https://beamline.io/components/avatar.md) - [Button](https://beamline.io/components/button.md) - [Empty state](https://beamline.io/components/empty-state.md) - [Label](https://beamline.io/components/label.md) - [Radio group](https://beamline.io/components/radio-group.md) - [Select](https://beamline.io/components/select.md) - [Skeleton](https://beamline.io/components/skeleton.md) - [Spinner](https://beamline.io/components/spinner.md) - [Stepper](https://beamline.io/components/stepper.md) ## Dependencies `lucide-react` ## Import ```tsx import { RecordImport } from "@beamline/record-import"; ``` ## Get it Record import is part of Beamline UI. Install the parts you need in your React app as compiled packages or editable source. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect) ## More in SaaS admin - [Analytics dashboard](https://beamline.io/components/analytics-dashboard): A SaaS overview in the app shell, fed by your metrics hook: range and segment filters drive KPIs, new and expansion revenue, channels, plan mix, uptime… - [Sales dashboard](https://beamline.io/components/sales-dashboard): A sales leader's week in one screen: closed won against quota and pace, pipeline coverage and win rate, the quarter's run toward target with the forecast… - [Product analytics](https://beamline.io/components/product-analytics): How people use the product: a funnel whose steps are the selector, where the people lost at a step went (saved as a cohort in one action), retention by… - [Retention analysis](https://beamline.io/components/retention-analysis): Retention as a question with its terms in view: people who did one event came back to do another, on exactly day N or on or after it, with days as… - [Session replay](https://beamline.io/components/session-replay): Session replay with its triage. Recordings are filtered by conditions (has errors, address contains, longer than) and saved filters shared with the team… - [Status dashboard](https://beamline.io/components/status-dashboard): An operations view of service health: the overall state in one line, every service with its status, uptime, latency now and 90 days of history, latency… - [Telemetry explorer](https://beamline.io/components/telemetry-explorer): Logs and the traces behind them. A stacked volume chart shows how many lines of each level arrived over the time in view, so a burst of errors reads at a… - [Dashboard panels](https://beamline.io/components/dashboard-panels): A dashboard of panels configured without code. Panels in a grid sized small, medium or large, each showing what it computes now: a number (coloured only… - [Dashboard controls](https://beamline.io/components/dashboard-controls): A dashboard's controls and the panels they drive. Variables, ad hoc filters (added from a key and a value, each removable), group by and the time range… - [Versioned dashboard](https://beamline.io/components/versioned-dashboard): A dashboard over a data source that has versions (a design model, a dataset, a release). The pinned source and version are named once in the header; each… - [Saved views](https://beamline.io/components/saved-views): Saved viewpoints of a model, grouped for review. Privacy (only you, or everyone on the project) and the group are words on every row; copying a link says… - [Query library](https://beamline.io/components/query-library): The team's saved queries, to reuse in the editor. The list is a rail: all or starred and a search at rest; author, source, tags (a query with any chosen… - [CRM pipeline](https://beamline.io/components/crm): A pipeline screen: KPIs and stage mix derived from a virtualised deals grid with inline edit, bulk moves and delete with undo; a row opens the deal in a… - [Pipeline views](https://beamline.io/components/pipeline-views): One dataset of deals seen through named views: a board by stage where each card's time in its stage is drawn against the stage's target and said past it… - [Pipeline record](https://beamline.io/components/pipeline-record): One piece of work for a contact, through its stages. The contact's records sit as tabs, each with its own stage and history. The record leads: its title… - [Contact profile](https://beamline.io/components/contact-profile): One customer on one page: who they are and how to reach them (fields edit in place), their lifecycle stage and owner, the deals they are in with what is… - [Customer requests](https://beamline.io/components/customer-requests): What customers asked for, linked to the work that answers it. By work item: each item with its status, how many requests it carries and how many of them… - [Helpdesk inbox](https://beamline.io/components/helpdesk-inbox): A support team's inbox: views with counts, a virtualised ticket queue with search, priority filters and live SLA clocks, and the open ticket with its… - [Shared inbox](https://beamline.io/components/shared-inbox): A team's inboxes where each status tab means the right thing for its place, and a rule that mirrors teammates' conversations into a shared inbox. Your… - [Intake triage](https://beamline.io/components/intake-triage): Incoming requests decided before work starts, and the rules that route them. Triage: the items waiting (key, title, reporter and source, label in its… - [Queue today](https://beamline.io/components/queue-today): A walk-in queue's day so far. Every number says its window (since opening), what it's out of, and when it was last refreshed; served carries its share of… - [Queue settings](https://beamline.io/components/queue-settings): A walk-in queue's settings, one tab per job. Bookings: adding booked visits to the queue as one sentence with its consequence and an example, a conflict… - [AI support chat](https://beamline.io/components/support-chat): The customer's side of AI support: an assistant that answers from your help centre with numbered citations, a thumbs up or down on every answer (a down… - [AI support console](https://beamline.io/components/support-console): The support team's side of AI support: a queue sorted by what is due first (who the assistant is still handling, who asked for a person, who waits), the… - [Team chat](https://beamline.io/components/team-chat): A team's messages in one screen: channels and direct messages with unread counts and mentions, who is online, the conversation with reactions, receipts… - [Meeting and call review](https://beamline.io/components/meeting-review): Everything a recorded call left behind on one screen: the recording with its transcript by speaker, an AI summary that streams in, action items with… - [Email automation](https://beamline.io/components/email-automation): An email automation seen three ways. Runs: each with how it ended (running, finished, failed, cancelled: four words, four marks) and filters with counts… - [Messaging journeys](https://beamline.io/components/messaging-journeys): One messaging automation from the inside: its steps in order on a spine with the team's notes travelling beside a step (never steps; orphaned and said… - [Notification preferences](https://beamline.io/components/notification-preferences): What reaches a person and where: events grouped by area down the side, channels (email, push, Slack, in-app) across the top, a switch per pair that saves… - [Changelog feed](https://beamline.io/components/changelog-feed): An in-app What's new page: release notes grouped by month with tags, versions, pictures and details, a tag filter with counts, entries since your last… - [Billing & invoices](https://beamline.io/components/billing): The billing page of a subscription: the plan with its seats and renewal, cancel and resume in place, the card on file with a checked update form, metered… - [Invoices](https://beamline.io/components/invoices): Accounts receivable in one screen: what is outstanding, overdue and paid, the invoices by status in a virtualised grid with bulk reminders, and each… - [Billing desk](https://beamline.io/components/billing-desk): A front desk's billing for one client with several animals. A hospital stay's daily sales are gathered into one invoice: open sales on a rail (chosen… - [Accounting workbench](https://beamline.io/components/accounting-workbench): Card transactions on their way to the books: Prepare, Review and Exported as stages with exception views that keep missing coding apart from missing… - [Reconciliation](https://beamline.io/components/reconciliation): Balances compared and statements checked: each bank account's statement balance beside the books', both dated and drawn on one scale, the difference said… - [Transaction review](https://beamline.io/components/transaction-review): New transactions made sense of, and the rules that do it next time. Review takes one card at a time as the screen's focal object: the merchant, the… - [Budget month](https://beamline.io/components/budget-month): A household's month budget, worked on. The month leads with what is left to budget, in large figures, beside income and spending as bars (spending read… - [Estimate share](https://beamline.io/components/estimate-share): Sending an estimate to the people who decide. Recipients from the customer's and the fleet's contacts, each by email and text (an address missing said on… - [Order closeout](https://beamline.io/components/order-closeout): Closing a repair order into an invoice. Its gates, each passed (success) or open (warning) with what to do: the balance paid (a payment recorded in… - [Purchase request](https://beamline.io/components/purchase-request): A purchase request, reviewed by the people who approve it. What is asked for: how often and for which dates, lines with quantity, rate and amount, each… - [Purchasing rules](https://beamline.io/components/purchasing-rules): A company's purchasing rules in one place. Approval exceptions (fallback review over an amount, over-budget routing, recurring documents approved once… - [Approval policy](https://beamline.io/components/approval-policy): A payment approval policy, edited as amount bands. Each band covers payments from one amount up to (not including) another, with its approvers in order… - [Projects](https://beamline.io/components/projects): A team's projects: the portfolio by health (on track, at risk, off track) with progress, lead, team and due date, filtered and searched; a project opens… - [Project home](https://beamline.io/components/project-home): A project's home joining model activity, delivery through the stages, syncs with connected tools and the project's details. Each section says its own… - [Project browser](https://beamline.io/components/project-browser): Projects from this computer, a phone library and a paired device, with their tracks and dated backups. A phone library prints its direction ("from your… - [Project directory](https://beamline.io/components/project-directory): A workspace's projects in a table: your role, who can open each one (its own column, with an icon and words), labels, status and when it changed. Labels… - [Project signals](https://beamline.io/components/project-signals): Projects with their signals apart: the health each lead wrote and how fresh that update is, drawn as the time since it against when the next was expected… - [Issue workbench](https://beamline.io/components/issue-workbench): One error issue under investigation: its all-time events and users labelled apart from what the environment and range filters scope, drawn per day with… - [Tracker desk](https://beamline.io/components/tracker-desk): A product team's work tracker from one person's seat. The inbox: Priority and Other with unread counts, notifications moved through with J/K or arrows… - [Engineering changes](https://beamline.io/components/engineering-changes): Engineering changes to a product: a draft revision edited beside the revision production uses, which doesn't change until the change is applied, with the… - [Workflow versions](https://beamline.io/components/workflow-versions): A workflow's versions with three questions answered apart: which version you're viewing, which draft you're editing and which one is running, as three… - [External review](https://beamline.io/components/external-review): A document reviewed with someone outside the team. Who holds the pen is one line at the top. Comments are kept in two threads by audience, the audience… - [Event evidence](https://beamline.io/components/event-evidence): What surrounded one error event, beside the issue: the feature flags evaluated before it, error volume per hour with flag changes marked (a change after… - [Correlation editor](https://beamline.io/components/correlation-editor): Building a link from a query's results to another source. In editor mode the results are outlined and every cell can start a link; the chosen row's… - [File manager](https://beamline.io/components/file-manager): Files and folders in one screen: the views (My files, Shared, Recent, Starred, Trash) with storage at the foot, a folder tree beside the files… - [Slide presenter](https://beamline.io/components/slide-presenter): A deck being presented, edited or watched. The slides in a numbered strip (a live slide marked by its kind, notes by a dot), the slide on stage with its… - [Signature fields](https://beamline.io/components/signature-fields): Preparing a document for signing: place signature, initials, date, text and checkbox fields on its pages for named signers. Choose a signer, then a field… - [Record catalogue](https://beamline.io/components/record-catalog): A catalogue of records kept by a small team. The list: search, a category multi-select and a status filter together, the count shown against the whole… - [Record editor](https://beamline.io/components/record-editor): A record list and the editor for one record, guarding unsaved changes. Changed fields are marked and counted; Cancel, Escape or choosing another record… - [Import runs](https://beamline.io/components/import-runs): Imports you can leave and come back to. The runs listed with their state on a tinted chip; one opened shows its file, record type, job and who started… - [Record settings](https://beamline.io/components/record-settings): How records are judged and signed. Flags show how many records carry each beside its switch: switching one off keeps past uses readable, delete is… - [Record setup](https://beamline.io/components/record-setup): How one kind of record is set up: its page layout edited on a real record as people will see it (a field's eye hides or shows it, required ones locked… - [Event registration](https://beamline.io/components/event-registration): An event's page with its registration and ticket. The event: artwork, host, title, the date and times in the event's own time zone (named beside them)… - [Ticket setup](https://beamline.io/components/ticket-setup): A seated event's tickets, led by what each type sells against its seats: per type its capacity as a figure against the seats mapped to it, a bar of sold… - [Lease setup](https://beamline.io/components/lease-setup): A new lease, set up on a unit in four steps. The term is drawn on the unit's occupancy beside the leases already on it, and its start and end are grips… - [Rental policy](https://beamline.io/components/rental-policy): A rental shop's period policy: any dates (with or without pickup and return times), fixed lengths or time slots, each with its own settings (default… - [Planner setup](https://beamline.io/components/planner-setup): A planner's settings that are easy to get wrong. Calendar events: turning them on is a choice, not a connection, so the card says where it really is… - [Stop runs](https://beamline.io/components/stop-runs): Stopping an automation as two commands that say what they do. Stop new runs takes no new ones while the runs already going carry on, the count falling as… - [Map annotations](https://beamline.io/components/map-annotations): Notes drawn on a chart over the real ground (a map base: coast, water, relief, towns, roads), the chart as large as the window allows. Lines, areas and… - [Flight record](https://beamline.io/components/flight-record): One recorded flight: its out, in, time and distance in the head, taken from the linked tracks; the tracks recorded around it drawn on the real ground (a… - [Flight route](https://beamline.io/components/flight-route): A route in the air, drawn on the real ground (a map base) as straight legs between waypoints, the chart as large as the window allows: the flown legs… - [Pre-flight briefing](https://beamline.io/components/preflight-briefing): A pilot's briefing before departure. Notices filtered by place and by whether they matter to this flight, each with its code, place, period (active now… - [Sign in](https://beamline.io/components/sign-in): The sign-in card: email and password, a one-time code or a magic link, passkeys and single sign-on, with validation, progress, errors and a signed-in… - [Sign up form](https://beamline.io/components/signup-form): The account creation card: single sign-on, name, work email and a password with strength and Caps Lock hints, terms consent, inline validation, your… - [Auth page](https://beamline.io/components/auth): The whole sign-in / sign-up route: product mark, a quiet dotted field with a light that follows the mouse, an optional notice, the SignIn and SignupForm… - [Onboarding checklist](https://beamline.io/components/onboarding-checklist): The first screen after sign-up: a welcome with how far set-up has come, a checklist of the few steps that make the product useful (each with why, how… - [Workspace switcher](https://beamline.io/components/workspace-switcher): Moving between workspaces and making a new one: a switcher for the top of your sidebar (the current workspace's mark, name and plan; a searchable list… - [Empty states](https://beamline.io/components/empty-states): The five empty moments every product has, written and wired: first use with a first step, no results with the filters to clear, an error with retry and a… - [Settings](https://beamline.io/components/settings): Profile and workspace settings with one draft and a real save handler, on grouped panels: photo upload, time zone with the local time, appearance cards… - [Admin users](https://beamline.io/components/admin-users): Your staff's view of every account: headline counts that follow the filters, a virtualised users table with search, status and plan filters and sorting… - [Roles & permissions](https://beamline.io/components/roles-permissions): What each role may do, as one matrix: permissions grouped by area down the side, roles across the top with their head counts, a check per cell; a group's… - [Security](https://beamline.io/components/account-security): A person's account security on one page: how protected they are at a glance with the next step to take, password change with strength and rules, two-step… - [API keys & webhooks](https://beamline.io/components/api-keys): The developer page of a SaaS: API keys with environment, scopes, last use and expiry, created through a form whose secret is shown once (copy it before… - [Integrations](https://beamline.io/components/integrations): A directory of the apps a product connects to: search and categories with counts, connected apps first with their state (Connected, Needs attention), a… - [Domain verification](https://beamline.io/components/domain-verification): Setting up a sending domain: the DNS records exactly as the provider gives them (type, name, value, priority, TTL), each with its own state and its name… - [Audit log](https://beamline.io/components/audit-log): Who did what, to what, when and from where, for a whole workspace: newest first and grouped by day, people with avatars and keys or systems with toned… Part of [Beamline UI: polished, editable React components and complete screens for custom applications](https://beamline.io/). [Build your own style from any look; tokens, fonts, radii, motion; not only colours](https://beamline.io/docs/customize).