Todos los componentes (204)

Valoración

Elección · Rating · .amset-rating

Qué es y cuándo usarlo

Estrellas para puntuar o para enseñar una media. Cuando se puede tocar es un grupo de radio, con un nombre en palabras por estrella («3 estrellas»); en solo lectura es una imagen con su texto («Valoración media: 4,3 de 5») y admite medias estrellas.

Cuándo usarlo

Pedir una opinión: la nota de un pedido o de un producto.
Enseñar la media con readOnly, showValue y count: «4,3 (128)». Una media a medio camino se pinta a media estrella y la cifra exacta va al lado; rounding="exact" pinta el porcentaje real.
shape="compact" (solo lectura) mete la nota y unas estrellas pequeñas en una pastilla, para listas y tarjetas.
size: estrellas de 16, 22 (por defecto) o 28 px; la etiqueta, la nota, la ayuda y el error crecen con ellas. outline pinta todas en oro y las llenas también con línea.
icon y unit cambian el símbolo y cómo se llama cada opción («1 nivel», «3 niveles»).

Cuándo no

El desglose de las opiniones por estrellas, con barras: RatingSummary.
Una encuesta de 0 a 10: NpsSurvey.
Un número que se escribe: NumberField.

Teclado: para puntuar, cada estrella es un radio nativo del mismo grupo: un solo Tab para entrar y salir, y las flechas mueven y eligen a la vez. Con allowsRemove, Supr o Retroceso la dejan vacía y avisan a onChange con null; volver a pulsar la estrella elegida con el ratón o el dedo también. Funciona igual controlada (value, que admite null para «sin puntuar») que sin controlar (initialValue). En solo lectura no es un control y no recibe el foco.

Accesibilidad: para puntuar es un radiogroup que se llama como la etiqueta, y cada estrella dice su número en palabras; la ayuda y el error (hint y error, las piezas de los campos) se leen como descripción del grupo, y con error el contorno de las vacías pasa a rojo. En solo lectura es una imagen (role="img") con la etiqueta, la nota y el máximo en su nombre. La estrella llena va en el token --amset-gold, medido a 3:1 sobre los fondos. Cada estrella pulsable mide al menos 24 px con ratón y 44 px con el dedo, sin huecos que pisen a la vecina. El foco es un anillo de 2 px alrededor de la estrella. hiddenLabel quita la etiqueta de la vista, no del lector.

Movimiento: con el ratón encima se ve la nota que quedaría antes de pulsar, y lo que se perdería sale en un oro apagado; la estrella apuntada crece un poco y la pulsada cede. Las estrellas se llenan con un fundido y la que se marca entra con un salto corto.

Contexto: va dentro de LocaleProvider (o de AmsetProvider), que decide cómo se escribe la nota: 4,3.

Aspecto fino: variables CSS --amset-rating-size (el lado de cada estrella: 16, 22 o 28 px según size), --amset-rating-slot (la separación entre estrellas), --amset-rating-padding (el aire alrededor de cada estrella pulsable), --amset-rating-color (la llena, --amset-gold), --amset-rating-empty (el contorno de la vacía), --amset-rating-stroke (su grosor), --amset-rating-stroke-filled (0 o 1: si la llena lleva también línea), --amset-rating-radius (las esquinas del foco), --amset-rating-font (la nota y el recuento) y --amset-rating-pill (el fondo de la compacta).

Cómo se ve

<Rating label="Valoración del servicio" value={nota} onChange={setNota} max={5} />
<Rating label="Media de los clientes (solo lectura)" initialValue={4} readOnly count={128} />

Props

Se importa con import { Rating } from '@amset/ui'. Las obligatorias van marcadas.

Prop	Tipo	Para qué sirve
`label`obligatoria	`string`	Que se esta valorando. Obligatorio: "4 de 5" a secas no dice nada.
`allowsRemove`	`boolean`	Volver a pulsar la estrella elegida (o Supr) deja la valoracion vacia.
`className`	`string`	Se une a las clases de la biblioteca, no las sustituye.
`count`	`number`	Cuantas valoraciones hay detras: "4,3 (128)".
`disabled`	`boolean`	—
`error`	`string`	—
`hiddenLabel`	`boolean`	La etiqueta solo para el lector de pantalla (la pastilla ya se explica sola).
`hint`	`string`	—
`icon`	`ReactNode`	Otro simbolo: un corazon, una llama. Cambia tambien `unit`.
`initialValue`	`number \| null`	La nota al empezar, sin controlarla desde fuera.
`max`	`number`	Cuantas estrellas hay. Por defecto, 5.
`onChange`	`(value: number \| null) => void`	Avisa con la nota elegida, o con `null` al quitarla (con `allowsRemove`).
`outline`	`boolean`	Las estrellas llenas tambien con contorno: mas fino, menos contundente.
`readOnly`	`boolean`	Ensena la media sin dejar tocarla. Admite decimales.
`rounding`	`RatingRounding`	Como se dibuja una media a medio camino. `exact` pinta el porcentaje real.
`shape`	`RatingShape`	`compact` mete la nota y unas estrellas pequeñas en una pastilla, para listas y tarjetas donde cinco iconos grandes se comen la fila. Solo lectura.
`showMax`	`boolean`	Con la nota, tambien el maximo: "4,0 de 5".
`showValue`	`boolean`	La nota al lado de las estrellas.
`size`	`"sm" \| "md" \| "lg"`	El lado de cada estrella: 16, 22 (por defecto) o 28 px.
`unit`	`RatingUnit`	Como se llama cada unidad, para el nombre de cada opcion.
`value`	`number \| null`	La nota, controlada desde fuera (con `onChange`). `null` es «sin puntuar»: asi se vacia sin pasar a `undefined`, que la soltaria del control. En solo lectura admite decimales.

Acepta además los atributos del elemento que pinta: className, style, data-*, aria-* y sus eventos.

Mandos

Estas variables CSS son la forma de adaptarlo. Se declaran sobre el selector del componente, no en :root: la hoja las redeclara en la propia regla y una declaración en el mismo elemento gana siempre.

Variable	Por defecto
`--amset-rating-size`	`1.375rem`
`--amset-rating-slot`	`0.25rem`
`--amset-rating-padding`	`0.1875rem`
`--amset-rating-color`	`var(--amset-gold)`
`--amset-rating-empty`	`var(--amset-border-bold)`
`--amset-rating-stroke`	`1.5`
`--amset-rating-stroke-filled`	`0`
`--amset-rating-radius`	`var(--amset-radius-sm)`
`--amset-rating-font`	`var(--amset-text-sm)`
`--amset-rating-pill`	`var(--amset-gold-soft)`

Cómo se cambia

.amset-rating {
  --amset-rating-size: ...;
  --amset-rating-slot: ...;
}

En el banco de pruebas

Cada estado y cada variante, para tocarlos de uno en uno, en su ficha de ui.amset.tech: