Each guide opens with a short answer, then follows one original teaching record through definitions, mechanism, worked examples, changed-context checks, misconceptions and bounded reporting.
The examples are stipulated for learning. The standards and specifications define the operational methods; the worked cases keep every input, transformation and limit visible so the reasoning can be repeated.
Mutation records preserve selected facts about individual changes, while their target remains a live node. Several writes can therefore queue several old values before one callback reads a single final attribute value.
The A→B→C teaching case follows record creation, batching, microtask notification, filters, takeRecords and callback writes without pretending that target is a snapshot.
A reliable audit keeps four clocks apart: when script performs each mutation, when the user agent queues its record, when the microtask checkpoint invokes the observer, and when callback code reads the live node. The old-value field belongs to one queued mutation; a callback-time getAttribute call belongs to the later live state. Keeping those timestamps separate prevents a common but serious reconstruction error.
The worked routes also test missing old values, attribute filters, removed subtrees, takeRecords and callback-created mutations. Each change-of-context check asks which evidence was actually retained and which later value must be measured rather than inferred.
This specialist guide belongs to the Websites root. It also connects to The Gold Standard of Education | Learning That Transfers into Life and the How X Works hub. The worked cases are original teaching examples; their numbers are stipulated so that the reasoning can be checked.
eduKateSG · Websites
Find your next learning step
Read the short answer first: MutationRecord.oldValue is the value before that record’s mutation when requested. target.getAttribute() in the callback reads the live value at callback time, after later mutations may already have occurred.
ROUTE 1 · CHAPTERS 1–4
Define the quantities
Name the quantities, reference conditions and reporting rules.
ROUTE 3 · CHAPTERS 9–12
Audit the evidence
Check instruments, algorithms, assumptions and rival explanations.
ROUTE 5 · CHAPTERS 17–20
Report and continue
Repair shortcuts, answer questions and follow verified routes.
Chapter contents
Define the quantities · Chapters 1–4
1. Name oldValue and the current value
2. Request attributeOldValue explicitly
Work the mechanism · Chapters 5–8
5. Work the A→B→C central case
Audit the evidence · Chapters 9–12
9. Audit removals and absent values
Transfer the reasoning · Chapters 13–16
14. Transfer to class-list diagnostics
Report and continue · Chapters 17–20
17. Repair oldValue is the previous callback value
18. Repair target is a snapshot
For an attribute mutation, MutationRecord.oldValue is the attribute value before that specific mutation when attributeOldValue was requested. Reading target.getAttribute() inside the later callback returns the element’s current value at callback time. Several mutations can therefore share one final current value but retain different old values.
Write the evidence in the order a reader can audit: the Websites quantity, its reference object, the observation or browser rule, the transformation, and the decision being made. Keeping those fields visible prevents a familiar label from hiding a changed basis.
Set data-state from A to B and then B to C in one task. The two records have oldValue A and B; inside the callback, getAttribute(‘data-state’) can return C for both records.
First-principles test: ask what physical, observational or algorithmic operation produces each value in this chapter. Then ask whether the second value could change while the first stays fixed. If it can, the two labels are not substitutes. For Websites, this counterfactual is often clearer than a definition learned in isolation.
Insert an awaited task boundary between the two writes. The callbacks can now observe B and then C as current values.
Evidence check: another reader should be able to reproduce the narrow result from the stored definitions, inputs and intermediate steps, then identify the nearest stronger claim that the evidence does not support.
Observer delivery and microtask timing must be tested against the current DOM and HTML standards.
oldValue is populated only when the observation options request it for attributes. Setting attributeOldValue true also implies attribute observation when attributes is omitted, while explicitly setting attributes false with attributeOldValue true is invalid.
Trace the mechanism before interpreting the result. For Websites, mark which value belongs to the source, which belongs to the measurement or layout algorithm, and which is a reported summary. A calculation is useful only when those roles remain attached.
Observe button with {attributeOldValue:true}. Change aria-expanded from false to true and record oldValue false.
Practical transfer: build two records that share the headline number but differ in the condition discussed here. If the correct interpretation changes, the omitted condition is decision-relevant and belongs in the report. This test turns a vocabulary distinction into a reusable Websites checking habit.
Observe with {attributes:true} but no attributeOldValue. The record still names the attribute but oldValue is null.
Practical check: keep one counterexample beside the worked case. If the wording fails when that one condition changes, narrow the sentence until it describes only the evidence actually in hand.
A null oldValue can mean not requested or previously absent; inspect the options and mutation context.
Each interested observer receives a MutationRecord in its record queue when the mutation is queued. The callback later receives a cloned list of queued records during mutation-observer notification. The record preserves its initialized old value even if the node changes again.
Use a compact decision table with columns for condition, input, operation, result and limit. This makes the comparison reproducible and exposes where a missing field would force an assumption instead of an observation.
Queue data-step 1→2, 2→3 and 3→4 before notification. Preserve three records in order and a final DOM read of 4.
Misconception check: a plausible output does not prove the right reference, denominator, ancestor, spectrum or observation rule was used. Reconstruct one intermediate step and one changed-context prediction. If either cannot be stated, keep the result provisional rather than strengthening its wording.
Call takeRecords before the callback. It empties and returns the queued records, changing what the callback later receives.
Transfer check: repeat the reasoning with one consequential condition changed while holding the rest fixed. State what changes, what stays comparable and why the original label alone was insufficient.
Application code should not assume a callback per write; records are batched for notification.
CHAPTER 4 OF 20 · Define the quantities
4. Separate record target from callback-time DOM
The record target identifies the node whose attribute changed. It is not a snapshot of the entire element. Other attributes, children and text read later can already reflect additional mutations not represented by that single record.
Preserve the raw inputs beside the derived result. If a later reader changes one condition, the original Websites reasoning should still be recoverable without reverse-engineering a rounded headline or an unlabeled screenshot.
A record says class changed from compact, while a later script also sets data-ready and replaces text. At callback time, target exposes all final states.
Evidence design: retain both a positive case and a near-miss. The positive case shows when the rule applies; the near-miss changes one consequential condition and shows when the conclusion fails. Together they teach the boundary of the Websites mechanism better than another unlabelled example.
Clone the element before the second script and compare the snapshot with the record target.
Audit check: retain the source version, units, settings, exclusions and rounding rule. A future correction should be able to alter one field without rebuilding the entire explanation from memory.
Cloning for diagnostics can change identity and event relationships; it is not a universal production strategy.
The central case starts data-mode=A. One synchronous function writes B, reads layout, then writes C. With attributeOldValue enabled, two records are queued. At notification, record 1 oldValue=A, record 2 oldValue=B, and current getAttribute is C for both.
Ask what would have to stay fixed for the comparison to be fair. Record those controls explicitly, then name the first uncontrolled condition that could reverse the conclusion. This is the practical transfer step, not an optional footnote.
Build a table with columns sequence, write, oldValue, current-at-callback and task. The table shows why reconstructing each new value from the final DOM alone is impossible without the next record or an application log.
Communication test: replace any sentence that says two things are “the same” or “different” with a sentence naming the operation, reference condition and supported consequence. The extra words are useful when they let a future reader repeat the decision without access to the original author.
Remove the second write. The sole record oldValue=A and callback current=B now look like a direct before/after pair.
Decision check: end with an action or interpretation that follows from the stated conditions, followed by a boundary sentence explaining when a specialist rule, local procedure or additional measurement is needed.
The worked values are original teaching data; real libraries may coalesce application state before DOM writes.
CHAPTER 6 OF 20 · Work the mechanism
6. Reconstruct intermediate new values carefully
For a sequence of attribute records on the same attribute, the next record’s oldValue can reveal the previous mutation’s new value. The last record’s new value may be read from the current attribute only if no later unobserved change intervened.
Write the evidence in the order a reader can audit: the Websites quantity, its reference object, the observation or browser rule, the transformation, and the decision being made. Keeping those fields visible prevents a familiar label from hiding a changed basis.
From old values A and B plus final current C, reconstruct A→B→C. Mark the reconstruction rule beside the table.
First-principles test: ask what physical, observational or algorithmic operation produces each value in this chapter. Then ask whether the second value could change while the first stays fixed. If it can, the two labels are not substitutes. For Websites, this counterfactual is often clearer than a definition learned in isolation.
Filter out the second record with a different observer configuration. A plus final C no longer proves whether B existed.
Evidence check: another reader should be able to reproduce the narrow result from the stored definitions, inputs and intermediate steps, then identify the nearest stronger claim that the evidence does not support.
Do not infer a complete history when records were filtered, taken, disconnected or produced by different observers.
attributeFilter limits which attribute names generate records. It does not freeze unlisted attributes. A callback reading the whole element can see changes that never entered this observer’s queue.
Trace the mechanism before interpreting the result. For Websites, mark which value belongs to the source, which belongs to the measurement or layout algorithm, and which is a reported summary. A calculation is useful only when those roles remain attached.
Observe only data-state. In the same task change data-state and aria-live. The record queue contains one data-state record, while callback-time aria-live already has its final value.
Practical transfer: build two records that share the headline number but differ in the condition discussed here. If the correct interpretation changes, the omitted condition is decision-relevant and belongs in the report. This test turns a vocabulary distinction into a reusable Websites checking habit.
Add aria-live to the filter and compare the additional record.
Practical check: keep one counterexample beside the worked case. If the wording fails when that one condition changes, narrow the sentence until it describes only the evidence actually in hand.
Attribute local names and namespaces require the DOM standard’s matching rules, especially outside HTML.
Setting an attribute may queue a mutation record even when application code believes it wrote an equivalent logical value. The DOM algorithm and serialization, not the business-state comparison, determine the observed mutation.
Use a compact decision table with columns for condition, input, operation, result and limit. This makes the comparison reproducible and exposes where a missing field would force an assumption instead of an observation.
Call setAttribute(‘data-count’,’5′) twice and inspect the records and old values in target browsers. Compare with a guarded write that first checks the string value.
Misconception check: a plausible output does not prove the right reference, denominator, ancestor, spectrum or observation rule was used. Reconstruct one intermediate step and one changed-context prediction. If either cannot be stated, keep the result provisional rather than strengthening its wording.
Change number 5 to string ‘5’ in application state while leaving the DOM string unchanged.
Transfer check: repeat the reasoning with one consequential condition changed while holding the rest fixed. State what changes, what stays comparable and why the original label alone was insufficient.
Engine conformance and framework diffing can change whether a DOM write is attempted; distinguish the layers.
When an attribute is removed, oldValue can hold the previous string and the current value becomes null. When an absent attribute is added, oldValue is null. The same null therefore needs the mutation direction and current state.
Preserve the raw inputs beside the derived result. If a later reader changes one condition, the original Websites reasoning should still be recoverable without reverse-engineering a rounded headline or an unlabeled screenshot.
Remove data-label=’ready’: oldValue ready, current null. Add it to an initially absent element: oldValue null, current ready.
Evidence design: retain both a positive case and a near-miss. The positive case shows when the rule applies; the near-miss changes one consequential condition and shows when the conclusion fails. Together they teach the boundary of the Websites mechanism better than another unlabelled example.
Remove and re-add before notification. Two records plus final ready distinguish the sequence.
Audit check: retain the source version, units, settings, exclusions and rounding rule. A future correction should be able to alter one field without rebuilding the entire explanation from memory.
Empty string and absent attribute are different states and must not be collapsed.
A MutationObserver callback can itself change attributes and queue later records. Those records belong to a subsequent notification cycle, so one callback’s current DOM reads can include its own writes while its input list describes earlier mutations.
Ask what would have to stay fixed for the comparison to be fair. Record those controls explicitly, then name the first uncontrolled condition that could reverse the conclusion. This is the practical transfer step, not an optional footnote.
Callback 1 receives A→B and writes data-audited=yes. A later callback receives the audit attribute record. Timestamp both lists.
Communication test: replace any sentence that says two things are “the same” or “different” with a sentence naming the operation, reference condition and supported consequence. The extra words are useful when they let a future reader repeat the decision without access to the original author.
Move the audit marker to an external log object. The extra mutation record disappears.
Decision check: end with an action or interpretation that follows from the stated conditions, followed by a boundary sentence explaining when a specialist rule, local procedure or additional measurement is needed.
Observer-driven writes can create unbounded microtask churn even without a ResizeObserver delivery-loop error.
Two observers on the same node can receive different record details because their options differ. One may request oldValue and another may not; one may filter attributes while another observes the subtree.
Write the evidence in the order a reader can audit: the Websites quantity, its reference object, the observation or browser rule, the transformation, and the decision being made. Keeping those fields visible prevents a familiar label from hiding a changed basis.
Observer O1 requests oldValue for data-state. O2 watches all attributes without oldValue. The same A→B write yields oldValue A for O1 and null for O2.
First-principles test: ask what physical, observational or algorithmic operation produces each value in this chapter. Then ask whether the second value could change while the first stays fixed. If it can, the two labels are not substitutes. For Websites, this counterfactual is often clearer than a definition learned in isolation.
Disconnect O1 before a second write. Only O2 receives the later record.
Evidence check: another reader should be able to reproduce the narrow result from the stored definitions, inputs and intermediate steps, then identify the nearest stronger claim that the evidence does not support.
Callback order should not be used to merge records unless observer identity and creation order are preserved.
takeRecords returns and clears currently queued records. disconnect stops future observation and discards pending records from ordinary callback delivery. These controls can explain gaps that a later current-state read cannot fill.
Trace the mechanism before interpreting the result. For Websites, mark which value belongs to the source, which belongs to the measurement or layout algorithm, and which is a reported summary. A calculation is useful only when those roles remain attached.
Write A→B, call takeRecords and store the returned record, then disconnect before B→C. The observer callback does not provide a continuous history.
Practical transfer: build two records that share the headline number but differ in the condition discussed here. If the correct interpretation changes, the omitted condition is decision-relevant and belongs in the report. This test turns a vocabulary distinction into a reusable Websites checking habit.
Reconnect before C→D and label the new observation interval.
Practical check: keep one counterexample beside the worked case. If the wording fails when that one condition changes, narrow the sentence until it describes only the evidence actually in hand.
A monitoring tool must record observation start, stop and manual drains to make omissions explicit.
Accessibility attributes often change several times during component initialization. A mutation record can prove an earlier aria-expanded value, while an assistive-technology audit also needs the final attribute, focus, role and accessible name.
Use a compact decision table with columns for condition, input, operation, result and limit. This makes the comparison reproducible and exposes where a missing field would force an assumption instead of an observation.
A disclosure writes false→true→false during setup. Records preserve old values false and true; callback current is false.
Misconception check: a plausible output does not prove the right reference, denominator, ancestor, spectrum or observation rule was used. Reconstruct one intermediate step and one changed-context prediction. If either cannot be stated, keep the result provisional rather than strengthening its wording.
Move initialization before observation and keep only user-triggered changes.
Transfer check: repeat the reasoning with one consequential condition changed while holding the rest fixed. State what changes, what stays comparable and why the original label alone was insufficient.
DOM attributes alone do not establish the full accessibility tree or user experience.
The class attribute is one serialized string, so oldValue preserves the prior serialization rather than a token-level diff. To explain which token changed, compare parsed token sets and keep ordering assumptions out of the conclusion.
Preserve the raw inputs beside the derived result. If a later reader changes one condition, the original Websites reasoning should still be recoverable without reverse-engineering a rounded headline or an unlabeled screenshot.
Old class is ‘card compact’, current is ‘card selected wide’. Compute removed {compact} and added {selected,wide}.
Evidence design: retain both a positive case and a near-miss. The positive case shows when the rule applies; the near-miss changes one consequential condition and shows when the conclusion fails. Together they teach the boundary of the Websites mechanism better than another unlabelled example.
Reorder the same tokens without changing the set and show why a string diff can overstate semantic change.
Audit check: retain the source version, units, settings, exclusions and rounding rule. A future correction should be able to alter one field without rebuilding the entire explanation from memory.
Class order can still affect textual tools even though selector matching treats tokens as a set.
Observing a host with subtree true does not automatically expose mutations inside a closed shadow root. Attribute reflection between properties and host attributes can also create several records around one component-state change.
Ask what would have to stay fixed for the comparison to be fair. Record those controls explicitly, then name the first uncontrolled condition that could reverse the conclusion. This is the practical transfer step, not an optional footnote.
A custom element reflects property open=true to the host attribute and updates internal content. The host observer receives the attribute record but not closed-root child changes.
Communication test: replace any sentence that says two things are “the same” or “different” with a sentence naming the operation, reference condition and supported consequence. The extra words are useful when they let a future reader repeat the decision without access to the original author.
Use an open shadow root in a test component and compare the observable boundary.
Decision check: end with an action or interpretation that follows from the stated conditions, followed by a boundary sentence explaining when a specialist rule, local procedure or additional measurement is needed.
Component encapsulation is intentional; consumers should prefer documented events and properties over internal mutation scraping.
CHAPTER 16 OF 20 · Transfer the reasoning
16. Transfer to analytics instrumentation
Analytics code may read current attributes after several state transitions and mislabel the final state as the new value for every queued record. Preserve record sequence or emit application events at the actual decision point.
Write the evidence in the order a reader can audit: the Websites quantity, its reference object, the observation or browser rule, the transformation, and the decision being made. Keeping those fields visible prevents a familiar label from hiding a changed basis.
A checkout button changes data-stage view→pressed→confirmed before the observer callback. Naive logging emits confirmed twice; the mutation table preserves both transitions.
First-principles test: ask what physical, observational or algorithmic operation produces each value in this chapter. Then ask whether the second value could change while the first stays fixed. If it can, the two labels are not substitutes. For Websites, this counterfactual is often clearer than a definition learned in isolation.
Emit one domain event at confirmation and compare its meaning with raw DOM records.
Evidence check: another reader should be able to reproduce the narrow result from the stored definitions, inputs and intermediate steps, then identify the nearest stronger claim that the evidence does not support.
Mutation observation is not a substitute for a well-defined analytics event model.
CHAPTER 17 OF 20 · Report and continue
17. Repair oldValue is the previous callback value
oldValue belongs to the individual mutation, not necessarily the value last seen by the callback. Batching allows several old values to arrive together after the DOM has reached a later state.
Trace the mechanism before interpreting the result. For Websites, mark which value belongs to the source, which belongs to the measurement or layout algorithm, and which is a reported summary. A calculation is useful only when those roles remain attached.
Rewrite ‘the prior callback value was A’ as ‘record 1 preserved A before its mutation; no callback ran between A→B and B→C.’
Practical transfer: build two records that share the headline number but differ in the condition discussed here. If the correct interpretation changes, the omitted condition is decision-relevant and belongs in the report. This test turns a vocabulary distinction into a reusable Websites checking habit.
Insert a task boundary so a callback does run between writes and compare the statement.
Practical check: keep one counterexample beside the worked case. If the wording fails when that one condition changes, narrow the sentence until it describes only the evidence actually in hand.
Microtasks scheduled by other APIs can complicate timing; retain a reproducible trace.
MutationRecord.target is the affected live node. It does not preserve the node’s full prior tree or attribute map. Only fields explicitly stored in the record are historical evidence.
Use a compact decision table with columns for condition, input, operation, result and limit. This makes the comparison reproducible and exposes where a missing field would force an assumption instead of an observation.
Keep the record, then change five other attributes before inspecting target. The target shows the new map while oldValue still returns the initialized string.
Misconception check: a plausible output does not prove the right reference, denominator, ancestor, spectrum or observation rule was used. Reconstruct one intermediate step and one changed-context prediction. If either cannot be stated, keep the result provisional rather than strengthening its wording.
Store a deliberate application snapshot at write time and label it separately from the standard record.
Transfer check: repeat the reasoning with one consequential condition changed while holding the rest fixed. State what changes, what stays comparable and why the original label alone was insufficient.
Full snapshots increase memory and privacy risk and should be scoped to the actual debugging need.
A useful receipt stores observer identity, options, target path, record type, attribute name and namespace, oldValue, record order, current callback value, task or microtask boundary, takeRecords calls and observation intervals.
Preserve the raw inputs beside the derived result. If a later reader changes one condition, the original Websites reasoning should still be recoverable without reverse-engineering a rounded headline or an unlabeled screenshot.
Package A→B→C with two records, one callback, final C and no filtered writes. Another reader can reconstruct the bounded transition sequence.
Evidence design: retain both a positive case and a near-miss. The positive case shows when the rule applies; the near-miss changes one consequential condition and shows when the conclusion fails. Together they teach the boundary of the Websites mechanism better than another unlabelled example.
Delete the observer options and show why null oldValue becomes ambiguous.
Audit check: retain the source version, units, settings, exclusions and rounding rule. A future correction should be able to alter one field without rebuilding the entire explanation from memory.
Instrumentation must avoid recording sensitive attribute content or user data unnecessarily.
A defensible report distinguishes the value before each queued mutation from the live value when the callback runs, states whether records were filtered or drained, and avoids inventing intermediate new values when the record chain is incomplete.
Ask what would have to stay fixed for the comparison to be fair. Record those controls explicitly, then name the first uncontrolled condition that could reverse the conclusion. This is the practical transfer step, not an optional footnote.
Write: ‘Two data-mode records preserved old values A and B; one later callback read current C. With no filtered or drained writes, the sequence supports A→B→C.’
Communication test: replace any sentence that says two things are “the same” or “different” with a sentence naming the operation, reference condition and supported consequence. The extra words are useful when they let a future reader repeat the decision without access to the original author.
Remove the no-drain evidence and narrow the sequence claim.
Decision check: end with an action or interpretation that follows from the stated conditions, followed by a boundary sentence explaining when a specialist rule, local procedure or additional measurement is needed.
Target-browser behaviour, framework scheduling and privacy constraints still require local verification.
Continue through the verified reading route
ResizeObserver content-box and border-box sizes
ResizeObserver content-box and border-box sizes. Use this to compare DOM mutation records with later layout-size observation.
Style queries and custom-property inheritance
Style queries and custom-property inheritance. Use this when attribute-driven state and computed CSS state diverge.
Intrinsic content size and placeholders
Intrinsic content size and placeholders. Use this when DOM changes occur while content rendering is skipped.
Frequently asked questions
Is oldValue the value from the previous callback?
Not necessarily. Several records can be batched before one callback.
Is MutationRecord.target a snapshot?
No. It is the live affected node; only the record fields preserve historical values.
Can I reconstruct every intermediate new value?
Only when the record chain is complete and no relevant writes were filtered, drained or unobserved.
Authoritative sources and further reading
WHATWG DOM Standard. Defines MutationObserver options, record queues, oldValue and mutation records.
WHATWG HTML event loops. Defines microtask checkpoints during which mutation observers are notified.
W3C ARIA in HTML. Provides the attribute-semantics context for ARIA mutation examples.
Return to the Websites subject guide, The Gold Standard of Education, or the How X Works hub.