Symbol - JavaScript | MDN

Toggle sidebar

Theme

OS default
Light
Dark

Español

Remember language Learn more

Symbol

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since septiembre de 2015.

* Some parts of this feature may have varying levels of support.

Symbol es un objeto incorporado cuyo constructor devuelve un symbol primitivo — también llamado Symbol value o simplemente Symbol — que está garantizado que sea único. Los Symbols se utilizan a menudo para añadir claves de propiedades únicas a un objeto que no sean iguales a las claves que cualquier otro código pueda añadir al objeto, y que están ocultas de cualquier mecanismo que otro código utilice normalmente para acceder al objeto. Esto permite una forma de encapsulation débil, o una forma débil de ocultación de información.

Se garantiza que cada llamada a Symbol() devuelve un único Symbol. Cada llamada a Symbol.for("key") devolverá siempre el mismo Symbol para un valor dado de "key". Cuando se llama a Symbol.for("key"), si se puede encontrar un símbolo con la clave dada en el registro global de símbolos, se devuelve ese Symbol. En caso contrario, se crea un nuevo Symbol, se añade al registro global de Symbols con la clave dada y se devuelve.

Descripción

Para crear un nuevo Símbolo primitivo, se escribe Symbol() con una cadena opcional como descripción:

js
let sym1 = Symbol();
let sym2 = Symbol("foo");
let sym3 = Symbol("foo");

El código anterior crea tres nuevos símbolos. Tenga en cuenta que Symbol("foo") no coacciona la cadena "foo" en un Symbol. Crea un nuevo Symbol cada vez:

Symbol("foo") === Symbol("foo"); // false

La siguiente sintaxis con el operador new lanzará un TypeError:

let sym = new Symbol(); // TypeError

Esto evita que los autores creen un objeto envolvente explícito Symbol en lugar de un nuevo valor Symbol y podría ser sorprendente ya que la creación de objetos envolventes explícitos alrededor de tipos de datos primitivos es generalmente posible (por ejemplo, new Boolean, new String y new Number).

Si realmente quieres crear un objeto envolvente Symbol, puedes utilizar la función Object():

js
let sym = Symbol("foo");
typeof sym; // "symbol"
let symObj = Object(sym);
typeof symObj; // "object"

Symbols compartidos en el registro global de Symbols

La sintaxis anterior utilizando la función Symbol() no creará un Symbol global que esté disponible en toda su base de código. Para crear Symbols disponibles en todos los archivos e incluso en todos los ámbitos (cada uno de los cuales tiene su propio ámbito global), utilice los métodos Symbol.for() y Symbol.keyFor() para establecer y recuperar Symbols del registro global de Symbols.

Encontrar las propiedades de los Symbols en los objetos

El método Object.getOwnPropertySymbols() devuelve una matriz de Symbols y permite encontrar las propiedades de los Symbols en un objeto determinado. Tenga en cuenta que cada objeto se inicializa sin propiedades Symbol propias, por lo que este array estará vacío a menos que haya establecido propiedades Symbol en el objeto.

Constructor

Symbol()

Crea un nuevo objeto Symbol. Está incompleto como constructor porque no soporta la sintaxis "new Symbol()".

Propiedades estáticas

Symbol.asyncIterator

Un método que devuelve el AsyncIterator por defecto para un objeto. Utilizado por for await...of.

Symbol.hasInstance

Un método que determina si un objeto constructor reconoce un objeto como su instancia. Utilizado por instanceof.

Symbol.isConcatSpreadable

Un valor booleano que indica si un objeto debe ser convertido a sus elementos de matriz. Utilizado por Array.prototype.concat().

Symbol.iterator

Un método que devuelve el iterador por defecto de un objeto. Utilizado por for...of.

Symbol.match

Un método que coincide con una cadena, también se utiliza para determinar si un objeto puede ser utilizado como una expresión regular. Utilizado por String.prototype.match().

Symbol.matchAll

Un método que devuelve un iterador, que devuelve las coincidencias de la expresión regular con una cadena. Utilizado por String.prototype.matchAll().

Symbol.replace

Un método que reemplaza las subcadenas coincidentes de una cadena. Utilizado por String.prototype.replace().

Symbol.search

Un método que devuelve el índice dentro de una cadena que coincide con la expresión regular. Utilizado por String.prototype.search().

Symbol.split

Un método que divide una cadena en los índices que coinciden con una expresión regular. Utilizado por String.prototype.split().

Symbol.species

Una función constructora que se utiliza para crear objetos derivados.

Symbol.toPrimitive

Un método que convierte un objeto en un valor primitivo.

Symbol.toStringTag

Valor de cadena utilizado para la descripción por defecto de un objeto. Utilizado por Object.prototype.toString().

Symbol.unscopables

Un valor de objeto cuyos nombres de propiedades propias y heredadas se excluyen de los enlaces de entorno with del objeto asociado.

Métodos estáticos

Symbol.for(key)

Busca los Symbols existentes con la key dada y los devuelve si los encuentra. En caso contrario, se crea un nuevo Symbol en el registro global de Symbols con la "key".

Symbol.keyFor(sym)

Recupera una clave de Symbol compartida del registro global de Symbols para el Symbol dado.

Propiedades de instancias

Symbol.prototype.description

Una cadena de sólo lectura que contiene la descripción del Symbol.

Métodos de instancia

Symbol.prototype.toString()

Devuelve una cadena que contiene la descripción del Symbol. Anula el método Object.prototype.toString().

Symbol.prototype.valueOf()

Devuelve el Symbol. Anula el método Object.prototype.valueOf().

Symbol.prototype[@@toPrimitive]

Devuelve el Symbol.

Ejemplos

Uso del operador typeof con Symbols

El operador typeof puede ayudarle a identificar los Symbols.

js
typeof Symbol() === "symbol";
typeof Symbol("foo") === "symbol";
typeof Symbol.iterator === "symbol";

Conversiones de tipos de Symbols

Algunas cosas a tener en cuenta cuando se trabaja con la conversión de tipo de Symbols.

Al intentar convertir un Symbol en un número, se producirá un TypeError. (e.g. +sym or sym | 0).
Cuando se utiliza la igualdad suelta, Object(sym) == sym devuelve true.
Symbol("foo") + "bar" lanza un TypeError (no se puede convertir Symbol en cadena). Esto impide crear silenciosamente un nuevo nombre de propiedad de cadena a partir de un Symbol, por ejemplo.
La conversión "más segura" String(sym) funciona como una llamada a Symbol.prototype.toString() con Symbols, pero ten en cuenta que new String(sym) será lanzado.

Iteración de Symbols y for...in

Los Symbols no son enumerables en las iteraciones for...in. Además, Object.getOwnPropertyNames() no devolverá las propiedades del objeto Symbol, sin embargo, puede utilizar Object.getOwnPropertySymbols() para obtenerlas.

js
let obj = {};

obj[Symbol("a")] = "a";
obj[Symbol.for("b")] = "b";
obj["c"] = "c";
obj.d = "d";

for (let i in obj) {
  console.log(i); // imprime en registro "c" y "d"
}

Symbols y JSON.stringify()

Las propiedades con clave de Symbol serán completamente ignoradas cuando se utilice JSON.stringify():

js
JSON.stringify({ [Symbol("foo")]: "foo" });
// '{}'

Para más detalles, consulte JSON.stringify().

Objetos envolventes de Symbols como claves de propiedades

Cuando se utiliza un objeto envolvente de un Symbol como clave de propiedad, este objeto será coaccionado a su Symbol envolvente:

js
let sym = Symbol("foo");
let obj = { [sym]: 1 };
obj[sym]; // 1
obj[Object(sym)]; // sigue siendo 1

Help improve MDN

Was this page helpful to you?

Yes No

Learn how to contribute

This page was last modified on 19 jun 2025 by MDN contributors.

View this page on GitHub • Report a problem with this content

Objetos globales
Symbol
Constructor
1. Symbol() constructor
Métodos estáticos
1. Symbol.for()
2. Symbol.keyFor()
Propiedades estáticas
Métodos de instancia
Propiedades de instancia
1. Symbol.prototype.description
Herencia
Object/Function
Métodos estáticos
Propiedades estáticas
Métodos de instancia
Propiedades de instancia
1. Object.prototype.__proto__
2. Object.prototype.constructor