Core D3 functionality for selecting DOM elements, binding data, and manipulating the document structure. D3's selection system is the foundation for all data-driven document transformations.
Functions for selecting single or multiple DOM elements using CSS selectors.
/**
* Select the first element matching the selector
* @param selector - CSS selector string
* @returns Selection containing the matched element
*/
function select(selector: string): Selection<HTMLElement, any, HTMLElement, any>;
function select(node: Element): Selection<HTMLElement, any, null, undefined>;
/**
* Select all elements matching the selector
* @param selector - CSS selector string
* @returns Selection containing all matched elements
*/
function selectAll(selector: string): Selection<HTMLElement, any, HTMLElement, any>;
function selectAll(nodes: ArrayLike<Element>): Selection<HTMLElement, any, null, undefined>;
/**
* Select the root document element
* @returns Selection containing the document element
*/
function selection(): Selection<HTMLElement, any, null, undefined>;Usage Examples:
import { select, selectAll } from "d3";
// Select single element
const svg = select("svg");
const bodyElement = select("body");
// Select multiple elements
const allParagraphs = selectAll("p");
const allCircles = selectAll("circle");
// Select by node reference
const element = document.getElementById("chart");
const selection = select(element);Methods for navigating and filtering selections within the DOM hierarchy.
interface Selection<GElement, Datum, PElement, PDatum> {
/**
* Select descendant elements for each element in the selection
* @param selector - CSS selector or function
* @returns New selection of descendant elements
*/
select(selector: string | ((datum: Datum, index: number, groups: GElement[]) => Element)): Selection<Element, Datum, GElement, Datum>;
/**
* Select all descendant elements for each element in the selection
* @param selector - CSS selector or function
* @returns New selection of all descendant elements
*/
selectAll<ChildElement extends BaseType, ChildDatum>(
selector: string | ((datum: Datum, index: number, groups: GElement[]) => ChildElement[] | ArrayLike<ChildElement>)
): Selection<ChildElement, ChildDatum, GElement, Datum>;
/**
* Filter elements based on data or selector
* @param filter - CSS selector, function, or data predicate
* @returns Filtered selection
*/
filter(filter: string | ((datum: Datum, index: number, groups: GElement[]) => boolean)): Selection<GElement, Datum, PElement, PDatum>;
/**
* Merge this selection with another selection
* @param other - Another selection to merge with
* @returns Combined selection
*/
merge(other: Selection<GElement, Datum, PElement, PDatum>): Selection<GElement, Datum, PElement, PDatum>;
/**
* Select the first child element for each element
* @param selector - Optional CSS selector to filter children
* @returns Selection of first child elements
*/
selectChild(selector?: string): Selection<Element, Datum, GElement, Datum>;
/**
* Select all child elements for each element
* @param selector - Optional CSS selector to filter children
* @returns Selection of all child elements
*/
selectChildren(selector?: string): Selection<Element, Datum, GElement, Datum>;
}Methods for getting and setting element attributes, styles, properties, and content.
interface Selection<GElement, Datum, PElement, PDatum> {
/**
* Get or set element attributes
* @param name - Attribute name
* @param value - Attribute value or function returning value
* @returns Selection for chaining or attribute value
*/
attr(name: string): string;
attr(name: string, value: Primitive | ((datum: Datum, index: number, groups: GElement[]) => Primitive)): Selection<GElement, Datum, PElement, PDatum>;
/**
* Get or set CSS classes
* @param names - Class names (space-separated)
* @param value - Boolean value or function returning boolean
* @returns Selection for chaining or boolean indicating presence
*/
classed(names: string): boolean;
classed(names: string, value: boolean | ((datum: Datum, index: number, groups: GElement[]) => boolean)): Selection<GElement, Datum, PElement, PDatum>;
/**
* Get or set CSS style properties
* @param name - Style property name
* @param value - Style value or function returning value
* @param priority - CSS priority (e.g., "important")
* @returns Selection for chaining or style value
*/
style(name: string): string;
style(name: string, value: Primitive | ((datum: Datum, index: number, groups: GElement[]) => Primitive), priority?: string): Selection<GElement, Datum, PElement, PDatum>;
/**
* Get or set element properties (like .value, .checked)
* @param name - Property name
* @param value - Property value or function returning value
* @returns Selection for chaining or property value
*/
property(name: string): any;
property(name: string, value: any | ((datum: Datum, index: number, groups: GElement[]) => any)): Selection<GElement, Datum, PElement, PDatum>;
/**
* Get or set text content
* @param value - Text value or function returning text
* @returns Selection for chaining or text content
*/
text(): string;
text(value: Primitive | ((datum: Datum, index: number, groups: GElement[]) => Primitive)): Selection<GElement, Datum, PElement, PDatum>;
/**
* Get or set inner HTML
* @param value - HTML string or function returning HTML
* @returns Selection for chaining or HTML content
*/
html(): string;
html(value: string | ((datum: Datum, index: number, groups: GElement[]) => string)): Selection<GElement, Datum, PElement, PDatum>;
}Methods for adding and removing elements from the DOM.
interface Selection<GElement, Datum, PElement, PDatum> {
/**
* Create, append and select new elements
* @param type - Element tag name or function returning element
* @returns Selection of newly created elements
*/
append<K extends keyof ElementTagNameMap>(type: K): Selection<ElementTagNameMap[K], Datum, GElement, Datum>;
append(type: string | ((datum: Datum, index: number, groups: GElement[]) => Element)): Selection<Element, Datum, GElement, Datum>;
/**
* Create, insert and select new elements before existing elements
* @param type - Element tag name or function returning element
* @param before - CSS selector or function indicating where to insert
* @returns Selection of newly created elements
*/
insert<K extends keyof ElementTagNameMap>(type: K, before?: string): Selection<ElementTagNameMap[K], Datum, GElement, Datum>;
insert(type: string | ((datum: Datum, index: number, groups: GElement[]) => Element), before?: string): Selection<Element, Datum, GElement, Datum>;
/**
* Remove elements from the DOM
* @returns Selection of removed elements
*/
remove(): Selection<GElement, Datum, PElement, PDatum>;
/**
* Insert clones of selected elements
* @param deep - Whether to perform deep clone
* @returns Selection of cloned elements
*/
clone(deep?: boolean): Selection<GElement, Datum, PElement, PDatum>;
}
/**
* Create a detached element (not yet added to DOM)
* @param name - Element tag name
* @returns Selection containing the detached element
*/
function create<K extends keyof ElementTagNameMap>(name: K): Selection<ElementTagNameMap[K], undefined, null, undefined>;
function create(name: string): Selection<Element, undefined, null, undefined>;Core D3 pattern for binding data arrays to DOM elements and handling enter/update/exit selections.
interface Selection<GElement, Datum, PElement, PDatum> {
/**
* Bind data to elements, creating enter/update/exit selections
* @param data - Array of data or function returning array
* @param key - Optional key function for object constancy
* @returns Update selection with enter() and exit() methods
*/
data<NewDatum>(data: NewDatum[] | ((datum: PDatum, index: number, groups: PElement[]) => NewDatum[]), key?: (datum: NewDatum | Datum, index: number, groups: GElement[] | NewDatum[]) => string): Selection<GElement, NewDatum, PElement, PDatum>;
/**
* Convenient shorthand for enter().append() and exit().remove()
* @param enter - Tag name or function for entering elements
* @param update - Optional function for updating elements
* @param exit - Optional function for exiting elements
* @returns Merged enter and update selection
*/
join<K extends keyof ElementTagNameMap>(
enter: K | ((enterSelection: Selection<EnterElement, Datum, GElement, PDatum>) => Selection<GElement, Datum, PElement, PDatum>),
update?: (updateSelection: Selection<GElement, Datum, PElement, PDatum>) => Selection<GElement, Datum, PElement, PDatum>,
exit?: (exitSelection: Selection<GElement, Datum, PElement, PDatum>) => void
): Selection<GElement, Datum, PElement, PDatum>;
/**
* Return the enter selection (data with no corresponding elements)
* @returns Enter selection for creating new elements
*/
enter(): Selection<EnterElement, Datum, PElement, PDatum>;
/**
* Return the exit selection (elements with no corresponding data)
* @returns Exit selection for removing old elements
*/
exit<OldDatum>(): Selection<GElement, OldDatum, PElement, PDatum>;
/**
* Get or set bound data for elements without joining
* @param value - Data value or function returning data
* @returns Selection for chaining or bound data
*/
datum(): Datum;
datum<NewDatum>(value: NewDatum | ((datum: Datum, index: number, groups: GElement[]) => NewDatum)): Selection<GElement, NewDatum, PElement, PDatum>;
}Usage Examples:
import { select } from "d3";
// Basic data binding
const data = [10, 20, 30, 40, 50];
select("svg")
.selectAll("circle")
.data(data)
.join("circle")
.attr("cx", (d, i) => i * 50 + 25)
.attr("cy", 50)
.attr("r", d => d / 2)
.attr("fill", "steelblue");
// Data binding with key function for object constancy
const people = [
{ id: 1, name: "Alice", age: 25 },
{ id: 2, name: "Bob", age: 30 },
{ id: 3, name: "Charlie", age: 35 }
];
select("#people")
.selectAll(".person")
.data(people, d => d.id) // Key function
.join("div")
.classed("person", true)
.text(d => `${d.name} (${d.age})`);Methods for adding and removing event listeners and dispatching custom events.
interface Selection<GElement, Datum, PElement, PDatum> {
/**
* Add or remove event listeners
* @param typenames - Event type names (space-separated)
* @param listener - Event listener function or null to remove
* @param options - Event listener options
* @returns Selection for chaining
*/
on(typenames: string): Function;
on(typenames: string, listener: null): Selection<GElement, Datum, PElement, PDatum>;
on(typenames: string, listener: (event: Event, datum: Datum) => void, options?: any): Selection<GElement, Datum, PElement, PDatum>;
/**
* Dispatch a custom event
* @param type - Event type name
* @param parameters - Optional event parameters
* @returns Selection for chaining
*/
dispatch(type: string, parameters?: any): Selection<GElement, Datum, PElement, PDatum>;
}
/**
* Get the current pointer position relative to the specified node
* @param event - Mouse or touch event
* @param target - Target element (defaults to event.currentTarget)
* @returns [x, y] coordinates
*/
function pointer(event: Event, target?: Element): [number, number];
/**
* Get positions of all pointers (for multi-touch)
* @param event - Touch event
* @param target - Target element
* @returns Array of [x, y] coordinate pairs
*/
function pointers(event: Event, target?: Element): Array<[number, number]>;Methods for iteration, inspection, and advanced selection manipulation.
interface Selection<GElement, Datum, PElement, PDatum> {
/**
* Call a function for each element in the selection
* @param func - Function to call for each element
* @returns Selection for chaining
*/
each(func: (datum: Datum, index: number, groups: GElement[]) => void): Selection<GElement, Datum, PElement, PDatum>;
/**
* Call a function with this selection as the first argument
* @param func - Function to call with selection
* @param args - Additional arguments to pass
* @returns Selection for chaining
*/
call(func: (selection: Selection<GElement, Datum, PElement, PDatum>, ...args: any[]) => void, ...args: any[]): Selection<GElement, Datum, PElement, PDatum>;
/**
* Returns true if the selection is empty
* @returns Boolean indicating if selection is empty
*/
empty(): boolean;
/**
* Returns array of all selected elements
* @returns Array of DOM elements
*/
nodes(): GElement[];
/**
* Returns the first non-null element in the selection
* @returns First DOM element or null
*/
node(): GElement | null;
/**
* Returns the number of elements in the selection
* @returns Count of selected elements
*/
size(): number;
/**
* Sort elements in the document based on data
* @param comparator - Comparison function
* @returns Selection for chaining
*/
sort(comparator?: (a: Datum, b: Datum) => number): Selection<GElement, Datum, PElement, PDatum>;
/**
* Re-order elements in document to match selection order
* @returns Selection for chaining
*/
order(): Selection<GElement, Datum, PElement, PDatum>;
/**
* Move each element to be the last child of its parent
* @returns Selection for chaining
*/
raise(): Selection<GElement, Datum, PElement, PDatum>;
/**
* Move each element to be the first child of its parent
* @returns Selection for chaining
*/
lower(): Selection<GElement, Datum, PElement, PDatum>;
}// Core selection types
type BaseType = Element | EnterElement | Document | Window | null;
interface EnterElement {
ownerDocument: Document;
namespaceURI: string;
appendChild(newChild: Node): Node;
insertBefore(newChild: Node, refChild: Node): Node;
querySelector(selectors: string): Element | null;
querySelectorAll(selectors: string): NodeListOf<Element>;
}
type Primitive = string | number | boolean | null | undefined;
interface Selection<GElement extends BaseType,
Datum,
PElement extends BaseType,
PDatum> {
// All methods defined above
}
// Utility types for selector functions
type ValueFn<T, Parameters extends readonly any[], Return> = (
this: T,
datum: Parameters[0],
index: number,
groups: Parameters[1] extends readonly (infer GElement)[] ? GElement[] : never
) => Return;